@hlix/cli 0.2.0

package/dist/package-WT5SD5LO.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import "./chunk-FYS2JH42.js";
+
+// package.json
+var name = "@hlix/cli";
+var version = "0.2.0";
+var license = "Apache-2.0";
+var description = "Command-line interface for the hlix control plane, built on @hlix/sdk.";
+var keywords = [
+  "hlix",
+  "cli",
+  "agents"
+];
+var homepage = "https://github.com/hlix-ai/hlix#readme";
+var repository = {
+  type: "git",
+  url: "git+https://github.com/hlix-ai/hlix.git",
+  directory: "packages/cli"
+};
+var bugs = {
+  url: "https://github.com/hlix-ai/hlix/issues"
+};
+var type = "module";
+var main = "./dist/index.js";
+var bin = {
+  hlix: "./dist/index.js"
+};
+var files = [
+  "dist",
+  "skills",
+  "THIRD_PARTY_NOTICES"
+];
+var engines = {
+  node: ">=20"
+};
+var publishConfig = {
+  access: "public"
+};
+var scripts = {
+  build: "tsup",
+  test: "bun test --isolate --timeout 20000",
+  typecheck: "tsc --noEmit",
+  prepublishOnly: "bun run typecheck && bun run build && bun test src/boundary.test.ts src/skill.test.ts src/binary.test.ts src/readme.test.ts"
+};
+var devDependencies = {
+  "@hlix/sdk": "^0.2.0",
+  ignore: "7.0.5",
+  tsup: "^8.5.0",
+  typescript: "^5.7.2",
+  "@types/bun": "latest"
+};
+var package_default = {
+  name,
+  version,
+  license,
+  description,
+  keywords,
+  homepage,
+  repository,
+  bugs,
+  type,
+  main,
+  bin,
+  files,
+  engines,
+  publishConfig,
+  scripts,
+  devDependencies
+};
+export {
+  bin,
+  bugs,
+  package_default as default,
+  description,
+  devDependencies,
+  engines,
+  files,
+  homepage,
+  keywords,
+  license,
+  main,
+  name,
+  publishConfig,
+  repository,
+  scripts,
+  type,
+  version
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hlix/cli",
+  "version": "0.2.0",
+  "license": "Apache-2.0",
+  "description": "Command-line interface for the hlix control plane, built on @hlix/sdk.",
+  "keywords": [
+    "hlix",
+    "cli",
+    "agents"
+  ],
+  "homepage": "https://github.com/hlix-ai/hlix#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hlix-ai/hlix.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hlix-ai/hlix/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "hlix": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "THIRD_PARTY_NOTICES"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test --isolate --timeout 20000",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run typecheck && bun run build && bun test src/boundary.test.ts src/skill.test.ts src/binary.test.ts src/readme.test.ts"
+  },
+  "devDependencies": {
+    "@hlix/sdk": "^0.2.0",
+    "ignore": "7.0.5",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.2",
+    "@types/bun": "latest"
+  }
+}

package/skills/hlix/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: hlix
+description: Import and configure local projects, then inspect Hlix projects and tasks from the terminal. Use when asked to scan or import a folder, initialize it, list projects, look up a task, read review evidence, or watch task status.
+---
+
+# hlix CLI
+
+Project setup and inspection for a Hlix workspace. Every command below is registered in
+the CLI — `skill.test.ts` compares this list against the command table and fails
+if they disagree, so this file cannot advertise something that does not exist.
+
+## Authentication
+
+```bash
+hlix auth login --workspace <id> [--base-url <url>]
+hlix auth status [--json]            # which credential, from where, does it work
+hlix auth logout [--yes] [--json]    # remove the stored credential file
+```
+
+Reads the key from a hidden terminal prompt, verifies it against the API
+**before** storing it, then writes it atomically to
+`~/.config/hlix/credentials.json` with mode 0600. The key is never printed back.
+
+`HLIX_API_KEY` overrides the stored file; `HLIX_BASE_URL` and
+`HLIX_WORKSPACE_ID` set the target and workspace. Use those in CI rather than
+running a login step.
+
+`--workspace` is required at login: an API key authenticates a user but names
+no workspace, so the caller states one. `hlix auth login` verifies the key
+against a real call **before** writing it, so a key that does not work is never
+stored.
+
+`auth status` names the credential's **source** — the environment or the stored
+file — and probes it against the API. It never prints the key, not even a
+prefix. `auth logout` removes the credential **file** only; a key supplied
+through `HLIX_API_KEY` is reported and left alone, because it belongs to the
+shell that set it. Removal asks for confirmation unless `--yes` is given, and
+refuses any path that is not a credential document this CLI wrote.
+
+## Where a command points
+
+Every command resolves its workspace and API through one chain, highest first:
+
+1. an explicit flag (`--workspace`, `--base-url`)
+2. the `HLIX_*` environment
+3. the nearest `.hlix/config.json`, walking up from the working directory
+4. the stored credential
+5. the built-in default (`https://server.hlix.ai`)
+
+The folder's binding therefore outranks the machine-wide credential: a folder
+bound to workspace A is queried against workspace A even when the last login
+named workspace B. A flag or environment variable that **contradicts** the
+folder's binding is not resolved by precedence — it exits `workspace_mismatch`
+naming both, because guessing which one was meant is how a push reaches the
+wrong tenant. `hlix auth login` is deliberately outside the chain, so signing in
+to a second workspace from inside a bound folder still works.
+
+`--cwd <dir>` makes any command operate on another directory, including the
+binding lookup. `hlix status` prints the resolved answer and the source that
+decided it.
+
+## Commands
+
+```bash
+hlix status [--json]                 # workspace, binding, local and cloud drift
+hlix projects list [--json]          # projects in the workspace
+hlix projects get [project-id] [--json]
+hlix init [folder] [--json]          # create committed project configuration
+hlix import [folder] [--dry-run] [--env-file <path>] [--history preserve] [--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 skill import <SKILL.md|folder> [--name <slug>] [--json]
+hlix agent import <markdown-file> [--name <name>] [--runtime <runtime>] [--profile <profile>] [--json]
+hlix mcp import <.mcp.json> [--server <name>] [--allow-stdio] [--json]
+hlix tasks list [--project <id>] [--status <status>] [--json]
+hlix tasks get <task-id> [--json]    # one task
+hlix tasks review <task-id> [--json] # the verified review evidence for a task
+hlix tasks watch <task-id> [--json]  # stream status changes until the task ends
+```
+
+`hlix --help` lists them; `hlix <command> --help` shows its usage. Every command
+also accepts `--cwd <dir>`.
+
+`hlix status` answers "where am I" in one screen: the resolved workspace and API
+with the source that decided each, the folder's binding and local revision, and
+whether the working tree or the cloud head has moved since the last sync. It
+reports rather than judges: a missing credential, an unreadable project file, a
+contradicting override and an unreachable API are all lines in the output, and
+the command itself always exits 0. An argument error — an unknown flag, a stray
+positional, a `--cwd` that is not a directory — is still exit 2, because it is
+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.
+The default history policy aborts on possible historical secrets. Explicit
+`--history preserve` keeps the full Git history after showing the risk.
+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`.
+
+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`.
+
+`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.
+
+## Machine output
+
+`--json` is a stable contract. Human output is not — do not parse it.
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "projects list",
+  "data": [ /* documented command result */ ]
+}
+```
+
+Failures use the same envelope with `error` instead of `data`:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "tasks get",
+  "error": { "code": "not_found", "message": "Task not found", "status": 404 }
+}
+```
+
+Branch on `error.code`, never on `error.message`. Codes: `unauthenticated`,
+`forbidden`, `not_found`, `conflict`, `invalid_request`, `bad_request`,
+`rate_limited`, `not_implemented`, `server_error`, `unreachable`,
+`missing_argument`, `invalid_usage`, `approval_required`, `cancelled`, `unknown_command`,
+`workspace_mismatch`, `not_initialized`, `scan_blocked`, `already_imported`,
+`workspace_required`, `invalid_base_url`, `missing_credential`, `unknown`.
+
+That list is the complete set — `skill.test.ts` compares it against every code
+the sources can emit in BOTH directions, so a code the CLI can return cannot go
+undocumented and a documented code cannot be one the CLI never returns.
+
+Transport-only inspection commands pass the API response through unchanged.
+Local project commands such as `import`, `push`, `pull`, and `sync` return the
+documented local result shape. The CLI selects columns for the human table only.
+
+`tasks watch --json` is the one exception to "one document": it emits **one
+envelope per line** (JSONL), because a live stream cannot be a single JSON
+document. Read it 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 |
+
+## Not available
+
+- **No execution commands.** There is deliberately no way to start a run,
+  execute a cycle or dispatch a task from this CLI.
+- **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.