@hlix/cli 0.7.1 → 0.8.0

package/dist/package-32h7hjkw.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+var s="@hlix/cli",e="0.8.0",n="SEE LICENSE IN LICENSE",a="Hlix Code and the hlix control-plane CLI.",r=["hlix","cli","agents"],l="https://hlix.ai",c="module",p="./dist/index.js",o={hlix:"./bin/hlix"},b=["bin","install.cjs","dist","skills","LICENSE","THIRD_PARTY_NOTICES"],u={node:">=22.19.0"},d={access:"public"},h={build:"rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --splitting --packages external --minify --banner '#!/usr/bin/env node'",test:'bun test src --path-ignore-patterns "**/*.integration.test.ts" --timeout 20000',typecheck:"tsc --noEmit",prepublishOnly:"bun run typecheck && bun run build && bun run test","test:integration":"NODE_ENV=test bun run ../../apps/backend/scripts/with-aimock.ts -- bun run ../../apps/backend/scripts/with-test-db.ts -- bun test --isolate --preload ../../apps/backend/test/helpers/pool-lifecycle.ts --timeout 60000 .integration.test.ts","build:binary":"bun run scripts/build-binary.ts","test:binary":"bun run build:binary && HLIX_TEST_BINARY=dist-native/hlix bun test src/__tests__/binary.test.ts --timeout 60000 && bun run scripts/smoke-binary.ts","test:integration:binary":"bun run build:binary && HLIX_TEST_BINARY=dist-native/hlix NODE_ENV=test bun run ../../apps/backend/scripts/with-aimock.ts -- bun run ../../apps/backend/scripts/with-test-db.ts -- bun test --isolate --preload ../../apps/backend/test/helpers/pool-lifecycle.ts --timeout 60000 src/__tests__/auth.integration.test.ts",postinstall:"node install.cjs"},m={"@agentclientprotocol/sdk":"0.21.1","@earendil-works/pi-tui":"0.85.1","@mastra/acp":"^0.4.1","@mastra/core":"1.72.0","@mastra/docker":"^0.9.0","@mastra/libsql":"1.23.0","@mastra/mcp":"2.1.0","@mastra/memory":"1.33.0",ignore:"7.0.8","jsonc-parser":"3.3.1","openapi-fetch":"^0.17.0","smol-toml":"1.8.0",yaml:"2.9.0",zod:"4.6.5"},x={"@hlix/sdk":"^0.3.0","@hlix/shared":"*","@types/bun":"latest",typescript:"^7.0.2"},y={"@hlix/cli-darwin-arm64":"0.8.0","@hlix/cli-darwin-x64":"0.8.0","@hlix/cli-linux-x64":"0.8.0","@hlix/cli-linux-arm64":"0.8.0"},k={name:s,version:e,license:n,description:a,keywords:r,homepage:l,type:c,main:p,bin:o,files:b,engines:u,publishConfig:d,scripts:h,dependencies:m,devDependencies:x,optionalDependencies:y};export{o as bin,k as default,m as dependencies,a as description,x as devDependencies,u as engines,b as files,l as homepage,r as keywords,n as license,p as main,s as name,y as optionalDependencies,d as publishConfig,h as scripts,c as type,e as version};

package/install.cjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// @hlix/cli's postinstall: put the standalone hlix binary where `hlix` points.
+//
+// npm installs exactly one of the optional @hlix/cli-<platform> packages (their
+// os/cpu/libc fields choose it). This links or copies its binary over
+// bin/hlix, so the command runs the binary directly with no Node process in
+// between. Without that package (--omit=optional, an unsupported platform) or
+// without this script (--ignore-scripts, pnpm), bin/hlix stays the small Node
+// wrapper, which finds the binary itself or runs the Node build.
+//
+// bin/hlix loads this file for `nativeBinary`, so the platform rules live once.
+"use strict"
+const { execFileSync } = require("node:child_process")
+const { copyFileSync, existsSync, linkSync, renameSync, rmSync } = require("node:fs")
+const { dirname, join } = require("node:path")
+
+const PLATFORMS = ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"]
+
+/** The platform package's binary, or the reason there is none. */
+function nativeBinary() {
+  const platform = `${process.platform}-${process.arch}`
+  if (!PLATFORMS.includes(platform)) return { reason: `no native build for ${platform}` }
+  if (process.platform === "linux" && !process.report?.getReport().header.glibcVersionRuntime) {
+    return { reason: "no native build for musl-based Linux" }
+  }
+  const pkg = `@hlix/cli-${platform}`
+  try {
+    const binary = join(dirname(require.resolve(`${pkg}/package.json`)), "hlix")
+    if (existsSync(binary)) return { binary }
+  } catch {
+    // Not installed: reported below.
+  }
+  return { reason: `${pkg} is not installed (npm skips it with --omit=optional)` }
+}
+
+function main() {
+  const found = nativeBinary()
+  if (!found.binary) {
+    process.stderr.write(`@hlix/cli: ${found.reason}; hlix will run its Node build.\n`)
+    return
+  }
+  const target = join(__dirname, "bin", "hlix")
+  const staged = `${target}.${process.pid}`
+  try {
+    try {
+      linkSync(found.binary, staged)
+    } catch {
+      copyFileSync(found.binary, staged)
+    }
+    // A binary that cannot run here must never replace the working wrapper.
+    const { version } = require("./package.json")
+    const reported = execFileSync(staged, ["--version"], { stdio: ["ignore", "pipe", "ignore"], timeout: 30_000 })
+    if (reported.toString().trim() !== version) throw new Error(`the ${version} binary reported ${reported.toString().trim()}`)
+    renameSync(staged, target)
+  } catch (error) {
+    rmSync(staged, { force: true })
+    process.stderr.write(`@hlix/cli: kept the Node wrapper (${error instanceof Error ? error.message : error})\n`)
+  }
+}
+
+module.exports = { nativeBinary }
+if (require.main === module) main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hlix/cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Hlix Code and the hlix control-plane CLI.",
   "keywords": [
@@ -12,9 +12,11 @@
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
-    "hlix": "./dist/index.js"
+    "hlix": "./bin/hlix"
   },
   "files": [
+    "bin",
+    "install.cjs",
     "dist",
     "skills",
     "LICENSE",
@@ -33,28 +35,36 @@
     "prepublishOnly": "bun run typecheck && bun run build && bun run test",
     "test:integration": "NODE_ENV=test bun run ../../apps/backend/scripts/with-aimock.ts -- bun run ../../apps/backend/scripts/with-test-db.ts -- bun test --isolate --preload ../../apps/backend/test/helpers/pool-lifecycle.ts --timeout 60000 .integration.test.ts",
     "build:binary": "bun run scripts/build-binary.ts",
-    "test:binary": "bun run build:binary && HLIX_TEST_BINARY=dist-native/hlix bun test src/binary.test.ts --timeout 60000 && bun run scripts/smoke-binary.ts",
-    "test:integration:binary": "bun run build:binary && HLIX_TEST_BINARY=dist-native/hlix NODE_ENV=test bun run ../../apps/backend/scripts/with-aimock.ts -- bun run ../../apps/backend/scripts/with-test-db.ts -- bun test --isolate --preload ../../apps/backend/test/helpers/pool-lifecycle.ts --timeout 60000 src/sync.integration.test.ts src/auth.integration.test.ts"
+    "test:binary": "bun run build:binary && HLIX_TEST_BINARY=dist-native/hlix bun test src/__tests__/binary.test.ts --timeout 60000 && bun run scripts/smoke-binary.ts",
+    "test:integration:binary": "bun run build:binary && HLIX_TEST_BINARY=dist-native/hlix NODE_ENV=test bun run ../../apps/backend/scripts/with-aimock.ts -- bun run ../../apps/backend/scripts/with-test-db.ts -- bun test --isolate --preload ../../apps/backend/test/helpers/pool-lifecycle.ts --timeout 60000 src/__tests__/auth.integration.test.ts",
+    "postinstall": "node install.cjs"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "0.21.1",
     "@earendil-works/pi-tui": "0.85.1",
     "@mastra/acp": "^0.4.1",
-    "@mastra/core": "1.71.0",
+    "@mastra/core": "1.72.0",
     "@mastra/docker": "^0.9.0",
     "@mastra/libsql": "1.23.0",
     "@mastra/mcp": "2.1.0",
-    "@mastra/memory": "1.30.0",
+    "@mastra/memory": "1.33.0",
     "ignore": "7.0.8",
     "jsonc-parser": "3.3.1",
     "openapi-fetch": "^0.17.0",
     "smol-toml": "1.8.0",
     "yaml": "2.9.0",
-    "zod": "4.5.4"
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@hlix/sdk": "^0.3.0",
     "@hlix/shared": "*",
     "@types/bun": "latest",
     "typescript": "^7.0.2"
+  },
+  "optionalDependencies": {
+    "@hlix/cli-darwin-arm64": "0.8.0",
+    "@hlix/cli-darwin-x64": "0.8.0",
+    "@hlix/cli-linux-x64": "0.8.0",
+    "@hlix/cli-linux-arm64": "0.8.0"
   }
 }

package/skills/hlix/SKILL.md

@@ -182,7 +182,8 @@ config key, which only picks the coder Hlix Code spawns on this machine.
 ## Commands
 
 ```bash
-hlix status [--json]                 # workspace, binding, local and cloud drift
+hlix status [--json]                 # workspace, binding, local and cloud drift, and how this hlix was installed
+hlix uninstall [--yes] [--json]      # remove an hlix the one-line installer put here; keeps your login
 hlix standards [--json]              # instruction files, skills, commands, MCP servers and subagents other agent tools left in this folder
 hlix rules [--edit] [--global] [--json]   # the rules files the coding agent reads; --edit opens one in $EDITOR
 hlix projects list [--json]          # projects in the workspace
@@ -190,11 +191,11 @@ hlix projects get [project-id] [--json]
 hlix projects delete <id|name> [--yes] [--json]
 hlix init [folder] [--project <id>] [--json]   # create committed project configuration; --project binds an existing cloud project
 hlix terminal [project-id] [--print] [--web] [--json]   # shell into the project's Coding Workspace (ssh here, or the browser terminal)
-hlix import [folder] [--dry-run] [--env-file <path>] [--history preserve|sanitize] [--include <path>] [--no-connect-origin] [--attach] [--yes] [--json]
+hlix import [folder] [--dry-run] [--env-file <path>] [--history preserve|sanitize] [--include <path>] [--yes] [--json]
 hlix sync [--dry-run] [--json]       # push or pull when only one side changed
-hlix pull [--force] [--yes] [--dry-run] [--json]
-hlix push [--dry-run] [--json]       # compare-and-swap a new immutable revision
-hlix mirror [--once] [--json]        # keep this folder a live mirror of the cloud files
+hlix pull [--dry-run] [--json]
+hlix push [--dry-run] [--json]       # push with an expected Git head
+hlix mirror [--json]        # keep this folder a live mirror of the cloud files
 hlix skill import <SKILL.md|folder> [--name <slug>] [--json]
 hlix agent import <markdown-file> [--name <name>] [--runtime <runtime>] [--duty <duty>] [--json]
 hlix mcp import <.mcp.json> [--server <name>] [--allow-stdio] [--json]
@@ -219,96 +220,15 @@ rejected before `status` runs at all.
 `tasks list` and `projects get` default to the project this folder is bound to,
 so both are usable with no arguments inside an imported project.
 
-Run `hlix import --dry-run` first. The report names secret **keys**, quarantined
-agent/skill/MCP resources, and Git-history findings, but never secret values.
-Hlix collects every project-local dotenv and credential file. It applies the
-standard development dotenv precedence automatically and preserves every other
-profile encrypted; `--env-file` is an explicit override.
-Git history is preserved by default. Possible historical secrets are warnings,
-with at most five redacted commit-and-file findings. To leave old commits out,
-use `--history sanitize` to upload a current-tree snapshot without changing local Git history. `--history preserve`
-and the legacy `--history abort-on-findings` remain accepted; neither blocks on
-historical findings. Nested repositories and declared submodules import their
-working files without their own Git metadata or history. Ignored nested
-repositories are skipped silently.
-
-Ordinary files over the upload limit are skipped with a named hint. If needed, history is omitted, then the largest folders are skipped until the snapshot fits. Import, init, and push refresh a marked Hlix-managed block in `.hlixignore` from shared stack detection and verified local generated paths. Personal lines outside the block are preserved byte-for-byte; `!` overrides outside the block take precedence even above it. Automatic rules never cover tracked files or secrets. Declared tools identify untracked build output without generation comments: Vite literal build.outDir or dist, Next .next (plus out for a default static export), Nuxt .nuxt/.output, Astro dist, Turbo .turbo, TypeScript literal tsconfig outDir, Webpack/Parcel dist defaults, and Rollup configured output.dir. Python build/dist/egg-info needs a declared build backend. Resolve output paths per package and configured root, applying recognized build-command output flags first. Unresolved root/config/CLI overrides disable inference for that tool rather than reverting to a default; configuration code is never executed. Track authored files in declared output directories or use ! overrides to keep them visible. Composer vendor requires a valid lockfile; local path dependencies stay visible. Untracked agent scratch and external nested repos are eligible only when they are not project source. Unknown paths stay visible. A refresh removes broad rules for folders that acquired tracked files or secrets; source outside declared build outputs stays visible. Human output adds one line: `Hlix ignored 6 generated folders — see .hlixignore`. Dry runs do not refresh files, and linked ignore targets or malformed blocks are left untouched. Folders with a managed block use these rules instead of blanket generated-directory exclusions. `--include <path>` restores one ignored path and persists it for later push/sync scans, subject to upload limits; it never includes Git metadata or bypasses secret protection. Push leaves the cloud unchanged when skipping would remove an existing cloud file. Symlinked `.hlixignore` files are read from their targets; an unreadable target leaves uploads unchanged with a permission warning.
-
-Never delete .git folders or files to get past this; use .hlixignore instead.
-
-The human scan report is ordered: uploaded / skipped / secrets / warnings /
-blocked. The secrets line says files move encrypted. Protected working-tree files are named individually; their values are
-never printed. The JSON dry run retains the full environment and file report.
-The upload manifest summarizes skip lists longer than 5,000 entries; local
-reports and push protection retain every skipped path.
-
-Current environment values are sent only in the authenticated finalization
-request and stored encrypted; they are never placed in the Git bundle.
-
-When the scan finds cloud setup commands, protected files, or quarantined
-resources, interactive imports ask for one explicit trust decision before any
-project is created or uploaded. Non-interactive and `--json` callers must first
-review `--dry-run`, then pass `--yes`; it never bypasses a scan blocker. A
-declined prompt exits as `cancelled`, while a caller that cannot prompt exits
-as `approval_required`.
-
-When the folder's Git `origin` remote (or its sole remote) is a GitHub
-repository, `import` checks it against the workspace: unowned and reachable
-through a GitHub App installation here, it is connected to the new project
-automatically, no question asked. Already attached to another project in this
-workspace, an interactive import asks whether to bind this folder there
-instead of creating a duplicate; `--yes`, `--json`, and any non-interactive
-run never attach on their own — they import repo-less and print a line
-naming the owning project, and `--attach` is the explicit, promptless opt-in
-that does the binding in any mode. No match, an unparseable remote, or a
-non-GitHub host changes nothing and is never a blocker. `--no-connect-origin`
-skips this whole check.
-
-Agent, skill, and MCP files found during a project scan stay quarantined until
-one of the explicit import commands above is run. Skill content and agents are
-scoped to the bound project. MCP imports send environment key names only;
-values remain in encrypted project secrets and the generated cloud config uses
-`${KEY}` placeholders, including remote authentication headers such as
-`Authorization: Bearer ${TOKEN}`. Literal-only headers are refused. Remote MCP URLs must use public HTTPS. Stdio servers
-require `--allow-stdio` and run only through a validated direct executable,
-never a shell.
-
-`sync` never guesses through a two-sided conflict. If only local changed it
-pushes; if only cloud changed it pulls; if both changed it exits with
-`conflict`.
-
-A folder bound with `hlix init --project <id>` has no local base revision. If
-the project already has cloud files, `hlix pull` brings them down and becomes
-that base. If it has none — a project created in the dashboard — `hlix push`
-(or `hlix sync`) uploads the folder as revision 1 and builds the project's
-Coding Workspace from it. Only a project with no revision at all can be
-bootstrapped that way: if the cloud already has a revision but this folder has no base, push leaves both copies unchanged and reports that it needs a pull first. `hlix
-pull` on a project with no cloud files exits `not_found` and names the way
-forward.
-
-`push`, `pull` and `sync` accept `--dry-run`: it prints the divergence — each
-side's generation, and how many files are local-only, cloud-only or differing —
-takes no action, and reports the verdict the real command would reach. A dry run
-that would end in `conflict` exits 1, as `import --dry-run` does for a blocker.
-
-`pull --force` is the destructive override, and it now asks before replacing
-local files: `--force` states "replace my changes", `--yes` states "do not ask".
-A `--json` or non-interactive caller cannot answer, so it exits
-`approval_required` pointing at `--dry-run`; a declined prompt exits `cancelled`.
-`--force` without local changes replaces nothing and does not prompt.
-
-`mirror` makes the folder follow the project's cloud Coding Workspace: it
-catches up once, then pulls whenever the cloud's files move (a task merged,
-another machine pushed, a cloud Hlix Code session edited) and pushes whenever
-a file here is saved. Every change still lands as a revision. When both sides
-changed the same file, the cloud's version wins and the local one is kept
-beside it as `<file>.local-<timestamp>`, named in a `mirror:` line. `.env` and
-the other protected files never move: unlike `pull`, the mirror never writes
-them here, and unlike `push`, a mirror push keeps the cloud's exactly as they
-were — change secrets with `hlix secrets`, or an explicit `hlix push`. `--once` does the catch-up pass and exits;
-`--json` prints one envelope per line (JSONL): `{ caughtUp, generation }` once the
-catch-up is done, then one per pass that moved something. Interactive
-`hlix` in a bound folder runs the same mirror while its cloud session is open.
+Run `hlix import --dry-run` first. The report includes file count, byte count and the number of protected files, without secret values. Review the upload, then use `--yes` to approve it. New projects receive a repository in **HLIX Repos**. Local Git history and origin stay intact.
+
+`--history preserve` retains local history after a complete secret scan. If the scan finds potential secrets or cannot complete, review the findings or use `--history sanitize` to upload current files. Source files travel through Git. Protected files use the encrypted secrets channel and never enter the source upload.
+
+`push`, `pull` and `sync` compare an immutable commit SHA and local file identities. They refuse to overwrite simultaneous local and remote changes. `--dry-run` reports the intended action. `mirror` checks for changes every 15 seconds and stops when cancelled; conflicts leave both copies intact and require manual resolution. Neither sync nor browsing committed files requires a Coding Workspace to wake up.
+
+Import keeps the project binding after an interrupted push. Use `hlix push` to resume against that same repository. A folder bound with `init` can bootstrap an empty repository, or pull an existing repository into an empty local folder. A nonempty local folder with no known base cannot overwrite existing remote source.
+
+Import skills, agents and MCP configuration explicitly with the resource commands listed above. They do not execute as a side effect of a source upload.
 
 ## Machine output
 
@@ -318,7 +238,7 @@ catch-up is done, then one per pass that moved something. Interactive
 {
   "schemaVersion": 1,
   "command": "projects list",
-  "data": [ /* documented command result */ ]
+  "data": [/* documented command result */]
 }
 ```
 
@@ -353,12 +273,12 @@ stream cannot be a single JSON document. Read them line by line.
 
 ## Exit codes
 
-| Code | Meaning |
-| --- | --- |
-| 0 | Success |
-| 1 | The command ran and failed |
-| 2 | Usage error — unknown command, bad flags, missing argument |
-| 3 | Authentication or permission failure |
+| Code | Meaning                                                    |
+| ---- | ---------------------------------------------------------- |
+| 0    | Success                                                    |
+| 1    | The command ran and failed                                 |
+| 2    | Usage error — unknown command, bad flags, missing argument |
+| 3    | Authentication or permission failure                       |
 
 ## Hlix Code, non-interactively
 
@@ -396,28 +316,12 @@ of yours.
 
 - **No execution commands** beyond `cycles create`. Starting a single task is
   not offered because the API does not implement it: `POST
-  /v1/api/tasks/{id}/execute` publishes no success response and answers `501`
+/v1/api/tasks/{id}/execute` publishes no success response and answers `501`
   by design. Work is dispatched by its cycle.
 - **No `tasks logs`.** The log endpoint is not part of the published API
   contract, and there is no log stream to follow. `tasks watch` streams task
-  *status*, which is a different thing and is named accordingly.
+  _status_, which is a different thing and is named accordingly.
 
 ### Import recovery and project deletion
 
-An interrupted import resumes the saved session in `.hlix/import.json` on the
-next `hlix import` in that folder. Keep that file and `.hlix/import.bundle`
-until it succeeds. A finalize timeout polls the same import for up to ten
-minutes; rerun the command if the wait ends. Secret values are re-read from
-local files only if finalization has not started. Restore changed files before
-resuming an upload; completed imports bind without rescanning. If the server
-confirms an unfinished session has expired, the CLI discards its saved recovery
-files, reports it, and starts a fresh import. A completed or still-finalizing
-session is never replaced just because its upload deadline passed.
-
-`hlix projects delete <id|name>` prints the selected project's name
-before deleting it. Names must match exactly and be unique; otherwise use the
-ID. Interactive deletion asks for confirmation. Non-interactive deletion,
-`--json`, and deletion of this folder's bound project require `--yes`.
-Deletion removes the cloud project; local files are kept.
-
-`push --dry-run` reports conflicts with exit 0 and makes no changes. The nonzero conflict verdict described above applies to `pull` and `sync`. Missing local push bindings and unreadable import recovery records likewise produce explicit no-op reports; no replacement project or upload is created.
+An interrupted import keeps its project binding. Retry with `hlix push`; source is stored in HLIX Repos rather than a resumable bundle session. Deleting a project removes its managed repository and encrypted project files.