@hagicode/cli 0.3.0 → 0.6.0

package/skills/hagi/references/session-data.md

@@ -0,0 +1,172 @@
+# Session Data
+
+Use this reference when an agent runs inside a HagiCode session and the user asks about their own projects, proposals, chat sessions, vaults, scheduled plans or installed skills.
+Read-only inspection comes first. Change state only when the user asked for that change in the conversation.
+
+## Runtime variables
+
+A HagiCode session can give you four variables. Each one is defined here, once:
+
+| Variable | Carries |
+| --- | --- |
+| `HAGI_API_BASE_URL` | Address of the backend that started the session. `hagi` reads it when no `--base-url` is given. |
+| `HAGI_VERSION` | Version of the HagiCode server that started the session. |
+| `HAGI_DEPLOYMENT_TYPE` | Deployment type of that server. |
+| `HAGI_API_LANG` | The user's effective AI language, `zh-CN` or `en-US`. `hagi` sends it as `Accept-Language`. |
+
+The server adds them to an agent run only when all of these hold:
+
+- the built-in `hagi` skill is installed and enabled;
+- the run is on Claude Code, Pi, OpenCode, GitHub Copilot or omp, the agent CLIs that load built-in skills at launch;
+- the value is one the server can determine. A value it cannot determine is left out, and the run still starts.
+
+A value the user already set in the environment is kept, not replaced.
+The variables carry facts about the server and the language only. They never carry a token or a file path.
+
+If a variable you rely on is absent, say that it is absent and ask the user. Do not guess a value, install software, or retry in a loop.
+
+## Connection
+
+Run `hagi` with no `--base-url` flag and no token when `HAGI_API_BASE_URL` is set; the variable is enough.
+
+- Pass `--base-url <url>` only when the user gives you an address.
+- If the CLI exits with code `2` and says no backend base URL is configured, the variable is missing from this session. Tell the user, and ask for the address. Do not guess one.
+- Use `--json` for every command whose output you will read or summarize.
+
+## Choosing the runner
+
+1. If `hagi` is on `PATH`, run `hagi ...`.
+2. Otherwise, if `node --version` reports 24 or newer, run `npx @hagicode/cli ...`.
+3. If neither is available, say that the CLI cannot run here and why. Continue without inventing data, and do not install Node.js or the CLI unless the user asks.
+
+## Read-only commands
+
+Run these freely to answer questions. Each list or get command is safe to repeat.
+
+### Projects
+
+```bash
+hagi project list --json
+hagi project repositories --id <project-id> --json
+```
+
+`project repositories` lists one project's repositories. Its paths are the only values a proposal's repository scope may name.
+
+### Proposals
+
+```bash
+hagi proposal list --json
+hagi proposal list --project-id <project-id> --active-only --json
+hagi proposal get --session-id <session-id> --json
+hagi proposal messages --session-id <session-id> --last 1 --json
+```
+
+`proposal get` and `proposal messages` only read. `proposal get --wait` polls the status until it settles and changes nothing.
+
+### Vaults
+
+```bash
+hagi vault list --json
+hagi vault files list --id <vault-id> --path <relative-dir> --json
+hagi vault files preview --id <vault-id> --path <relative-file> --json
+```
+
+`vault files preview` reads one file. Preview only the files the user's question needs.
+
+### Chat sessions
+
+```bash
+hagi chat list --json
+hagi chat list --project-id <project-id> --active-only --json
+```
+
+### HagiTasks
+
+```bash
+hagi hagitask list --json
+hagi hagitask schema --task-id <task-id> --json
+hagi hagitask get --session-id <session-id> --json
+hagi hagitask messages --session-id <session-id> --last 1 --json
+```
+
+Read the schema before creating a HagiTask session. Its `parameters` give the input keys, and `inputSchema` is the JSON Schema the input must satisfy.
+
+### Scheduled plans
+
+```bash
+hagi plan list --json
+hagi plan get --id <plan-id> --json
+```
+
+### Sagas
+
+```bash
+hagi saga list --project-id <project-id> --json
+hagi saga status <saga-id> --project-id <project-id> --json
+hagi saga items <saga-id> --project-id <project-id> --json
+```
+
+These queries read the selected project's Saga files without initializing or repairing them, refreshing runtime status,
+or executing acceptance commands. Status is a fresh `saga-status/2` observation; its `updatedAt` is not the stored
+execution heartbeat in `runtime/status.json`. `init` installs resources and `new` creates a Saga, so run either only
+when the user explicitly asks for that change. Contract and lifecycle operations run through `hagi saga` with the execution token rules in `references/saga.md`.
+
+### Skills
+
+```bash
+hagi skills local list --json
+hagi skills gallery search --query <keyword> --json
+hagi skills gallery detail --id <gallery-id> --source <source> --json
+hagi skills trusted list --json
+```
+
+`hagi skills local list --json` returns one item per installed skill. Read these fields from each item:
+
+- `origin`: `user` for a skill the user installed, `built-in` for a skill the server ships. An item with no `origin` is a user skill.
+- `builtIn.enabled`: whether a built-in skill is on. It is present only for built-in skills. For user skills, availability does not apply.
+- `builtIn.version`: the version the release recorded for a built-in skill. It may be absent.
+- `managedInstallMetadata.version`: the version of a user skill installed through the gallery, when recorded.
+
+## State-changing commands
+
+Run these only when the user has asked for that action in this conversation.
+First name the action and its target (the id, the title or the name), then run it.
+A question such as "what is in my plan" is not a request to run, enable, disable or delete it.
+
+| Family | Commands that change state |
+| --- | --- |
+| `project` | `create`, `update`, `delete` |
+| `proposal` | `create`, `optimize-description`, `generate`, `annotate`, `execute`, `archive`, `status`, `complete`, `send` |
+| `vault` | `create`, `update`, `delete` (`delete --delete-local-files` also removes files) |
+| `chat` | `create`, `archive`, `delete`, `send` |
+| `hagitask` | `create`, `send` |
+| `plan` | `create`, `update`, `enable`, `disable`, `delete`, `run` |
+| `saga` | `init`, `new`, `session create` |
+| `skills` | `local enable`, `local disable`, `local uninstall`, `gallery install`, `trusted upsert`, `trusted delete`, `trusted reset` |
+
+A `send` or `run` starts agent work, and `execute` and `generate` start it too. Treat those as changes of the same kind.
+
+`saga session create` creates a chat session for a Saga Worker and records it in the Saga's `runtime/sessions.md`. Creating a Worker changes state, so run it only when the user or a Saga run explicitly asks for it. It takes the execution token from `SAGA_EXECUTION_TOKEN` only, and with `--path` it calls the backend to find the project. See [`saga.md`](saga.md#worker-sessions).
+
+A `send` with Steer (`--steer`, or `HAGI_SEND_STEER` set in the calling shell) inserts its text into a running turn. The result says which happened: `steered` means a running task took it, and `queued` means no running task did, so it went out as the next message. `HAGI_SEND_STEER` belongs to the calling shell; the backend does not set it inside agent sessions.
+
+`hagitask create` with a Super Commit prompt (`--prompt-id auto-compose-commit.<locale>`) creates commits in a code repository, and with `--need-push` publishes them. Start it only when the user asked for it in this conversation, and add `--need-push` only when the user asked for a push. See [`super-commit.md`](super-commit.md).
+
+`skills local enable` and `skills local disable` change whether a built-in skill loads. The change applies to agent runs that start afterwards; a run already in progress keeps its skills. Built-in skills cannot be uninstalled through the CLI.
+
+Before `proposal create`, the proposal's repository scope is settled. Take the writable and read-only repositories from the user's request, or infer them from the session's repository scope when the session states one. When neither gives the scope, ask the user and offer the project's repositories from `project repositories --id <project-id> --json` as the choices. Do not guess the scope, and do not widen the writable list. The scope is written into the chief complaint as a `Repository scope` section; see [`proposal-flow.md`](proposal-flow.md#repository-scope).
+
+When you name the action and its target before running `proposal create`, name its repository scope too.
+
+## Failure handling
+
+| Exit code | Meaning | What to tell the user |
+| --- | --- | --- |
+| `2` | No base URL, or a usage error | The session did not provide `HAGI_API_BASE_URL`, or the command was malformed. Name the missing piece. |
+| `21` / `23` | Unauthorized / forbidden | The backend rejected the request. Report the code; do not try a token. |
+| `24` | Not found | Name the id that was not found and suggest a `list` command to find the right one. |
+| `30` | Operation failed: the backend refused a change and returned a result with `succeeded` false, for example `skills local enable` or `disable` on a name that is not a built-in skill | Quote the backend message from the output and stop. Nothing changed. |
+| `60` | Transport or connection failure | Say the backend is unreachable at the named base URL. Do not retry in a loop, and do not guess another address. |
+| other non-zero | HTTP or unknown error | Quote the error message and stop. |
+
+When a command fails, report the failure. Do not fill the gap with guesses about the user's data.

package/skills/hagi/references/super-commit.md

@@ -0,0 +1,106 @@
+# Super Commit through `hagi`
+
+Use this reference when a user asks to commit the uncommitted changes of a code repository, to publish them, or to explain or check a Super Commit run.
+
+Super Commit commits the uncommitted changes in a code repository. It runs as a separate session, not as part of the proposal lifecycle. It creates commits, and with `--need-push` it also publishes them. Treat it as a state-changing action: start it only when the user asked for it.
+
+For what the archive commit does, and how it differs from Super Commit, see [openspec-workflow.md](openspec-workflow.md#two-kinds-of-commit).
+
+## Start it: a prompt, not a preset task
+
+Super Commit is started with a prompt id:
+
+```bash
+hagi hagitask create --title <title> --project-id <project-id> --prompt-id auto-compose-commit.en-US --json
+```
+
+Use the locale that matches the user's language in place of `en-US`. The prompt id alone marks the session as a Super Commit.
+
+Super Commit is a prompt, not a preset task. It has no preset task id and no schema, so `hagi hagitask schema` does not apply to it. Do not pass `--task-id` or `--input` for it.
+
+Use the name Super Commit in your explanation to the user. The prompt id appears only inside commands.
+
+## Options
+
+Every option below is accepted by `hagi hagitask create`. The CLI checks these rules before any network call, and a violation is a usage error with exit code `2`.
+
+| Option | Meaning |
+| --- | --- |
+| `--repository-path <path>` | MonoSpecs sub-repository to commit in, for example `repos/cli`. |
+| `--need-push` | Publish the commits after they are created. Add it only when the user asked for a push. |
+| `--pull-rebase` | Run `git pull --rebase` before the push. It has effect only with `--need-push`, and only when the run stays on the current branch. |
+| `--target-branch-mode <mode>` | Which branch the commits go on. Modes are below. |
+| `--target-branch-name <name>` | Name of the branch to create. It needs `--target-branch-mode new-custom`. |
+
+Branch modes:
+
+- `current`: commit on the branch that is checked out now.
+- `new-custom`: create the branch named by `--target-branch-name` before the first commit. It needs a name. `--target-branch-name` without this mode is a usage error.
+- `ai-generated-new`: create a new branch with a name the backend generates, before the first commit.
+
+## Server-owned choices
+
+The Git identity, the co-author trailer and the sign-off setting come from the user's saved server settings. The CLI has no option for them.
+
+Do not invent a flag for them, and do not put them in `--message`. If the user wants a different co-author for a run, tell them that the CLI has no option for it and ask them to change the saved setting.
+
+## Read the result
+
+After the session settles (see "Who drives each step"), read the final message:
+
+```bash
+hagi hagitask messages --session-id <id> --last 1
+```
+
+The run ends with a result block:
+
+- `## Commits Created`: every planned commit was made, and the push happened if one was requested.
+- `## Commits Incomplete`: at least one commit failed, files were left uncommitted, or a requested push was skipped or failed.
+
+Then read these lines:
+
+- `**Commits:**` the commit count, for example `2`, or `1 of 2` when the run is incomplete.
+- `**Push:**` the push outcome, for example `pushed to origin/<branch>`, or `skipped (reason)`.
+- A numbered list of the commits, without hashes.
+
+Report the result as it is:
+
+- For `## Commits Created`: report the commit count and, if a push was requested, the push outcome.
+- For `## Commits Incomplete`: report what was left undone. Do not say the commit succeeded.
+- Retry through `hagi hagitask send --session-id <id> --content <text>` only when the user asks for it.
+
+The result contains no commit hashes. To read them, run `git log` in the target repository.
+
+## Explicit request
+
+Starting a Super Commit creates commits in a repository, and with `--need-push` publishes them. So:
+
+- Start one only when the user asked for it in this conversation.
+- Add `--need-push` only when the user asked for a push. If the user asks for a Super Commit and does not mention a push, leave `--need-push` out.
+- After `hagi proposal execute` and a settled wait, if code changes remain uncommitted, offer a Super Commit and wait for the user's answer. Do not start one.
+- Never start one as a side effect of another lifecycle command.
+
+The web Git tab runs the same feature.
+
+## Who drives each step
+
+| Step | Who |
+| --- | --- |
+| `hagi hagitask create --prompt-id auto-compose-commit.<locale>` | the agent, only on request |
+| The commit work | an AI run inside the backend |
+| Following the run | the agent, with `hagi hagitask get --session-id <id> --wait --json` |
+| Archiving the finished session | automatic, by the default rule `ai-commit-auto-archive` |
+
+Monitor the run with:
+
+```bash
+hagi hagitask get --session-id <id> --wait --json
+```
+
+Read the `status` and the `wait` object:
+
+- Optimizing, Openspecing, Executing and Archiving mean the run is still going.
+- WaitingForReply means a person must answer.
+- A timeout (exit code `31`) is reported with the last status. Do not retry in a loop.
+
+The default rule `ai-commit-auto-archive` archives the finished session automatically. So the agent runs no `archive` or `complete` for a Super Commit session. The rule is a user setting and may be off. Do not assume the session is archived: read `status`, and if the status is not Archived, report it as it is.

package/skills/hagi/references/validation.md

@@ -0,0 +1,164 @@
+# Validation
+
+Run the smallest relevant set after changes.
+Documentation-only updates do not require the full code validation stack, but cross-links and package metadata assumptions still need confirmation.
+
+## Documentation and skill checks
+
+Confirm these paths resolve and link correctly:
+
+- `repos/cli/README.md`
+- `repos/cli/skills/README.md`
+- `repos/cli/skills/hagi/SKILL.md`
+- `repos/cli/skills/hagi/agents/openai.yaml`
+- `repos/cli/skills/hagi/references/*.md`
+
+Check that every command named in the references is registered: the `hagi` help output after a build lists the same families and subcommands.
+
+## Repository scope rule check
+
+The repository scope rule for `proposal create` must appear in three files. Each one is checked on its own, and one file that still has the rule does not stand in for another:
+
+- `SKILL.md` carries the core rule: the writable and read-only lists, and the `project repositories` query.
+- `references/proposal-flow.md` carries the `Repository scope` section: the query step, the `Writable repositories:` and `Read-only repositories:` lists, and the example that begins its chief complaint with that section.
+- `references/session-data.md` carries the state-changing rule: the scope is taken from the user or the session, and the agent asks when neither gives it instead of guessing.
+
+Run this from `repos/cli` after editing any of the three:
+
+```bash
+grep -n "Repository scope" skills/hagi/SKILL.md skills/hagi/references/proposal-flow.md
+grep -n "Read-only repositories" skills/hagi/SKILL.md skills/hagi/references/proposal-flow.md
+grep -n "project repositories" skills/hagi/SKILL.md skills/hagi/references/proposal-flow.md skills/hagi/references/session-data.md
+grep -n "ask the user" skills/hagi/SKILL.md skills/hagi/references/proposal-flow.md skills/hagi/references/session-data.md
+```
+
+Each of the three files must match the lines listed for it above. A file that is missing a match fails the check, and it is fixed in the skill folder, not by copying the rule from another file.
+
+Confirm also that no skill file names `--writable-repo` or `--readonly-repo`, and that every `proposal create` example passes a chief complaint that begins with the `Repository scope` section.
+
+## HagiTask command check
+
+The `hagitask` command group must appear in the README and in each skill file that lists command families, and no file may document the retired `autotask` command. Run this from `repos/cli`:
+
+```bash
+for f in README.md skills/hagi/SKILL.md skills/hagi/references/cli-usage.md skills/hagi/references/session-data.md skills/hagi/references/super-commit.md skills/hagi/references/openspec-workflow.md; do
+  grep -q "hagitask" "$f" && echo "ok   hagitask in $f" || echo "FAIL hagitask missing from $f"
+done
+grep -rniE "autotask|auto-task" README.md skills --exclude=validation.md | grep -vi "migrat" || echo "ok   no autotask command documented"
+```
+
+Each file must print `ok`. The last grep lists only the migration notes (lines that say "migrat"), so any other match is a stale `autotask` reference and fails the check. This file is excluded from that grep because it names the pattern itself.
+
+## Workflow and Super Commit check
+
+Run this from `repos/cli` after editing `references/openspec-workflow.md`, `references/super-commit.md`, or any file that links them. Each line must print `ok`.
+
+1. Both references exist and are linked from `SKILL.md` and `skills/README.md`:
+
+```bash
+for f in skills/hagi/references/openspec-workflow.md skills/hagi/references/super-commit.md; do
+  [ -f "$f" ] && echo "ok   exists $f" || echo "FAIL missing $f"
+done
+for f in skills/hagi/SKILL.md skills/README.md; do
+  for t in openspec-workflow.md super-commit.md; do
+    grep -q "$t" "$f" && echo "ok   $f links $t" || echo "FAIL $f does not link $t"
+  done
+done
+```
+
+2. No README or skill file shows the retired `--task-id compose-commit` form. This check does not scan this file, which names the pattern itself. The id may remain as test data in `tests/commands/hagitask.test.ts`, the one allowed place, and that file is outside this scan:
+
+```bash
+grep -rn --exclude=validation.md -e "--task-id compose-commit" README.md skills
+status=$?
+if [ "$status" -eq 0 ]; then
+  echo "FAIL retired compose-commit example found above"
+elif [ "$status" -eq 1 ]; then
+  echo "ok   no --task-id compose-commit in README.md or skills"
+else
+  echo "FAIL grep could not run"
+fi
+```
+
+3. Every option the two references name is registered in the built CLI. Build first (`pnpm run build`), then run:
+
+```bash
+check() {
+  local command="$1"; shift
+  for option in "$@"; do
+    node ./dist/cli.js $command --help | grep -q -- "$option" && echo "ok   $command $option" || echo "FAIL $command $option is missing"
+  done
+}
+check "proposal get" --session-id --wait --timeout --interval --grace --json
+check "proposal messages" --session-id --last --json
+check "hagitask get" --session-id --wait --timeout --interval --grace --json
+check "hagitask messages" --session-id --last --json
+check "hagitask create" --prompt-id --repository-path --need-push --pull-rebase --target-branch-mode --target-branch-name
+```
+
+4. Both references have a "Who drives each step" section and both name `--wait`. Each count must be at least `1`:
+
+```bash
+grep -c "Who drives each step" skills/hagi/references/openspec-workflow.md skills/hagi/references/super-commit.md
+grep -l -- "--wait" skills/hagi/references/openspec-workflow.md skills/hagi/references/super-commit.md
+```
+
+## Built-in copy consistency check
+
+The embedded skill exists twice: `repos/cli/skills/hagi` is the only place it is edited, and `repos/built-in-skills/content/hagi` is the copy the server ships as the built-in `hagi` skill. Run this from the monorepo root to confirm the two match:
+
+```bash
+diff -r repos/cli/skills/hagi repos/built-in-skills/content/hagi
+```
+
+The expected result is no output, which means the folders are identical. Any output names a file that differs, is missing from one side, or is extra on one side.
+
+- If the check reports a difference, fix it by editing only `repos/cli/skills/hagi`. Never edit the bundle copy by hand.
+- Refreshing the bundle copy and its content hash is a separate follow-up in the bundle repository. It is not part of a CLI change, and a skill change leaves the check reporting differences until that follow-up runs.
+- After the repository scope edit, the bundle copy must be recopied from `repos/cli/skills/hagi` and its hash refreshed. Doing that needs write access to `repos/built-in-skills`. Until then, sessions that load the built-in `hagi` skill run the older text, with no `project repositories` guidance.
+- In a standalone CLI checkout the bundle is not beside the CLI. Replace `repos/built-in-skills/content/hagi` with the path to the `content/hagi` folder of a checked-out built-in skills bundle, for example `<path-to-built-in-skills>/content/hagi`.
+
+## Maintainer validation commands
+
+When command behavior, metadata, or packaging changes are involved, run the smallest relevant subset:
+
+```bash
+cd repos/cli
+pnpm run build
+pnpm run typecheck
+pnpm test
+node ./dist/cli.js --help
+node ./dist/cli.js proposal --help
+```
+
+If only a specific command changed, also verify that command's help directly.
+
+## Saga Worker session command
+
+Run this when `src/commands/saga/session.ts`, the Saga runtime helpers (`project.ts`, `safeWrite.ts`, `sessionRecord.ts`),
+the run prompt or these references changed:
+
+```bash
+cd repos/cli
+pnpm exec vitest run tests/commands/saga-session-create.test.ts tests/runtime/saga/appendContained.test.ts tests/runtime/saga/project.test.ts tests/runtime/saga/sessionRecord.test.ts
+pnpm exec vitest run tests/runtime/saga/assets.test.ts tests/docs
+node ./dist/cli.js saga session create --help
+```
+
+The command test covers argument validation, token rejection, selector matching, the `saga.*` metadata, the `sessions.md`
+append and the failed-record report. The help check prints the parameters, the metadata keys and the metadata limits.
+
+## Package publish-surface check
+
+Run this when `package.json`, publish contents, or release metadata changed. The Saga asset check and the package check
+are offline:
+
+```bash
+cd repos/cli
+pnpm exec vitest run tests/runtime/saga/assets.test.ts
+pnpm run pack:check
+```
+
+The npm tarball ships `dist`, `README.md`, `skills/**`, and only
+the allowlisted Saga resources, including the hidden `.gitignore` template. `pack:check` verifies the actual package
+contents and rejects source maps or unexpected resource files.