Make human-language universally accessible (npm, crates.io, Docker)#38
Conversation
Adding .gitkeep for PR creation (default mode). This file will be removed when the task is complete. Issue: #37
Adds a public API surface for human-language so it can be consumed as a library, command-line tool, and HTTP microservice. Implements the npm side of issue #37. - package.json: drop private flag, add main/types/bin/exports/files, declare engines.node >= 20, add start/cli/test scripts. - js/src/index.{js,d.ts}: re-export the public API with TypeScript declarations. - js/src/cli.js: `human-language` CLI with transform/entity/property/ search/serve/version/help subcommands. Heavy modules are imported lazily so `--version` and `--help` stay quiet and fast. - js/src/server.js: node:http microservice exposing /healthz, /version, /, /transform, /entity/:id, /property/:id, /search. Supports Accept: text/plain;codec=lino for LiNo output. Dependencies are injectable for tests. - js/src/config.js: lino-arguments style precedence (CLI > env > defaults) with --key=value, --key value, -p, and -- support. - js/src/transformation/lino-format.js: renders Q/P sequences in links-notation form, including `[A or B or C]` for ambiguous tokens. - js/src/version.js: package metadata loader (no import attributes). - Tests: 35 new gating tests across config (11), lino-format (7), server (11), and cli (6); wired into run-unit-tests.mjs.
Adds a Rust crate under rust/ that mirrors the pure-function helpers of
the JavaScript package. Same name (human-language), same version (0.1.0),
ready for crates.io publication alongside the npm package.
- rust/Cargo.toml: cdylib + rlib + binary, MIT, repo/keywords set; opt-in
wikidata-client feature for the future network port.
- rust/src/{tokenize,routing,settings,lino}.rs: ports of the JS modules
the SPA/CLI consume — tokenize/n-grams/stop-words/property-indicators,
hash parse+serialize, locale quotes + flag map, Links Notation render.
- rust/src/bin/cli.rs: `human-language` binary with tokenize, parse-hash,
lino-sequence, version, help subcommands.
- rust/tests/parity.rs: 10 parity tests pinned against the JS unit suites
so contracts stay in lockstep.
- rust/rust-toolchain.toml, rust/rustfmt.toml, rust/changelog.d/: pipeline
scaffolding adopted from the rust-ai-driven-development-pipeline-template.
Verified locally: cargo fmt --check, cargo clippy --all-targets -D warnings,
cargo test (22 unit + 10 parity tests pass).
Adds a multi-stage Dockerfile and a compose example so the same API surface that's published to npm and crates.io is also reachable as a Docker container — issue #37 R4. - Dockerfile: node:22-alpine, drops to the `node` user, sets sensible defaults via HUMAN_LANGUAGE_* env vars, and ships an inline Node-based HEALTHCHECK against /healthz so orchestrators can see liveness without needing curl in the image. ENTRYPOINT runs `human-language serve`. - .dockerignore: keeps the build context to runtime essentials. - examples/docker-compose.yml: local bring-up with a persistent volume for the Wikidata file cache.
Adds two GitHub Actions workflows alongside the existing js.yml: - rust.yml gates PRs on cargo fmt, cargo clippy, and cargo test (Linux, macOS, Windows). On version-bumping pushes to main, it runs cargo publish against crates.io. Adopted from rust-ai-driven-development- pipeline-template, trimmed to this repo's surface. - release.yml is triggered when package.json's version advances on main (or via workflow_dispatch with force_publish). It re-runs the unit suite as a gate, then publishes to npm with provenance (Sigstore trusted publishing) and a multi-arch image to ghcr.io, then cuts a GitHub release with auto-generated notes. Both pipelines use a small detect-version-bump helper: - js/scripts/check-package-version.mjs - rust/scripts/check-cargo-version.mjs The scripts diff the version against HEAD~1 and write should_publish to $GITHUB_OUTPUT, so the publish jobs are skipped on commits that don't move the version.
konard
changed the title
The previous URL (linksplatform/Documentation/blob/main/doc/LinksNotation.md) returns 404 and has no Web Archive snapshot, causing the JS workflow's lychee broken-link check to fail. Switch to the canonical repository URL already used throughout the issue #37 case study docs.
Working session summaryI'll wait for the notification. This summary was automatically extracted from the AI working session output. |
🤖 Solution Draft LogThis log file contains the complete execution trace of the AI solution draft process. 💰 Cost: $11.436811📊 Context and tokens usage:Claude Opus 4.7: (3 sub-sessions)
Total: (7.8K new + 319.8K cache writes + 12.5M cache reads) input tokens, 122.1K output tokens, $11.326917 cost Claude Haiku 4.5:
Total: (622 new + 40.9K cache writes + 288.8K cache reads) input tokens, 5.9K output tokens, $0.109895 cost 🤖 Models used:
📎 Log file uploaded as Gist (4551KB)Now working session is ended, feel free to review and add any feedback on the solution draft. |
🔄 Auto-restart 1/5Detected uncommitted changes from previous run. Starting new session to review and commit or discard them. Uncommitted files: Auto-restart will stop after changes are committed or discarded, or after 4 more iterations. Please wait until working session will end and give your feedback. |
Working session summaryAll CI checks pass and the PR is in CLEAN/MERGEABLE state. The uncommitted Working tree is clean, all 14 CI checks are passing (the 5 skipped ones are gated correctly: Pages deploys only on main, cargo publish only on version bumps), and PR #38 is in CLEAN/MERGEABLE state with no outstanding review comments. This summary was automatically extracted from the AI working session output. |
🔄 Auto-restart 1/5 LogThis log file contains the complete execution trace of the AI solution draft process. 💰 Cost: $0.446943📊 Context and tokens usage:
Total: (144 new + 37.7K cache writes + 307.9K cache reads) input tokens, 2.3K output tokens, $0.446943 cost 🤖 Models used:
📎 Log file uploaded as Gist (4964KB)Now working session is ended, feel free to review and add any feedback on the solution draft. |
✅ Ready to mergeThis pull request is now ready to be merged:
Monitored by hive-mind with --auto-restart-until-mergeable flag |
This reverts commit 0d0b469.
|
There should be js.yml and rust.yml, as per
Reread: #37 As we need to ensure all changes are correct, consistent, validated, tested, documented, logged and fully meet each and all discussed requirements in widest possible sense (check issue description and all comments in issue and in pull request, make sure each and every requirement listed before actually checking if they were addressed). Ensure all CI/CD checks pass. |
|
🤖 AI Work Session Started Starting automated work session at 2026-05-12T09:24:32.603Z The PR has been converted to draft mode while work is in progress. This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback. |
Work session completeUpdated PR #38 for the latest review:
Fresh CI on commit |
🤖 Solution Draft LogThis log file contains the complete execution trace of the AI solution draft process. 💰 Cost estimation:
📊 Context and tokens usage:
Total: (299.7K + 13.9M cached) input tokens, 53.6K output tokens, $19.272025 cost 🤖 Models used:
📎 Log file uploaded as Repository (81243KB)Now working session is ended, feel free to review and add any feedback on the solution draft. |
✅ Ready to mergeThis pull request is now ready to be merged:
Monitored by hive-mind with --auto-restart-until-mergeable flag |
1 participant
Summary
Resolves #37. Makes
human-languageconsumable through the requested surfaces while keeping the branch aligned with the latest PR review:main,types,bin,files, public export subpaths, and ahuman-languageCLI.rust/with[lib],[[bin]], parity tests, and directlino-arguments/lino-objects-codecintegration./healthz, andexamples/docker-compose.yml.Review update
The workflow layout now matches the review request: this branch has exactly the language workflows
.github/workflows/js.ymland.github/workflows/rust.yml. The separate.github/workflows/release.ymlwas removed.js.ymlnow owns JS syntax checks, unit tests, link checks, local/deployed Playwright checks, Pages deployment, npm publishing, GHCR Docker publishing, and GitHub release creation. Publish jobs are gated behind the test/link/e2e chain and apackage.jsonversion bump (or manualforce_publish).The previous shim/optional-dependency claims are gone. JS now depends directly on
lino-arguments@^0.3.0andlino-objects-codec@^0.4.0; Rust now depends directly onlino-arguments = "0.3.0",lino-objects-codec = "0.2.1", andclapfor the derive expansion used by the parser.Tests and validation
npm cinode js/scripts/check-mjs-syntax.mjsnode js/scripts/run-unit-tests.mjsPORT=18080 npm run test:e2e:local(local port 8000 was already occupied)npm pack --dry-runruby -e "require 'yaml'; YAML.load_file('.github/workflows/js.yml'); YAML.load_file('.github/workflows/rust.yml')"cargo fmt --checkcargo clippy --all-targets -- -D warningscargo clippy --all-targets --all-features -- -D warningscargo testcargo test --all-targetscargo test --all-targets --all-featurescargo packagegit diff --checkDocker build was not run locally because this runner does not have the
dockerbinary installed.Documentation
docs/case-studies/issue-37/was updated to reflect the actual implementation, deferred follow-ups, direct dependency usage, and thejs.yml/rust.ymlworkflow split.