{"_id":"@bin.zhou/personal-cli-agent","_rev":"2-bb9164222b1c2a03eb447490269d39d7","name":"@bin.zhou/personal-cli-agent","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@bin.zhou/personal-cli-agent","version":"0.1.0","_id":"@bin.zhou/personal-cli-agent@0.1.0","maintainers":[{"name":"bin.zhou","email":"743028972@qq.com"}],"bin":{"agent":"dist/cli/main.js"},"dist":{"shasum":"4859d08f770b382649ca8e1d21676da04aa18031","tarball":"https://registry.npmjs.org/@bin.zhou/personal-cli-agent/-/personal-cli-agent-0.1.0.tgz","fileCount":276,"integrity":"sha512-jZ8XEIlmRSUWEY/b73vVFD+hAiVs+3/3iEhXo9KD7lAMF1pyCLFkcBZIZVevjGWCGSgYfRY7DGdhV4yO84MVNQ==","signatures":[{"sig":"MEUCIQD1WfcVJhg+CJGcNnT/uhSOjpLsegq4zaBa9m2eQm4QwAIgco9M0rJRMkAsPc9oMbArc5jBx/9skQEXQK9v9Ryd4uM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":813601},"type":"module","engines":{"node":">=20"},"scripts":{"dev":"node --experimental-strip-types --enable-source-maps src/cli/main.ts","lint":"tsc --noEmit","sbom":"npm sbom --sbom-format cyclonedx --sbom-type application","test":"vitest run","audit":"node scripts/audit-gate.mjs","build":"tsc -p tsconfig.json","prepack":"npm run build","test:ci":"vitest run --coverage","typecheck":"tsc --noEmit","test:watch":"vitest","secret-scan":"vitest run test/security/canary-sweep.test.ts test/security/negative.test.ts","test:security":"vitest run test/security","prepublishOnly":"npm run build && npm run typecheck && npm run test:ci && npm run test:security && npm run audit"},"_npmUser":{"name":"bin.zhou","email":"743028972@qq.com"},"_npmVersion":"11.16.0","description":"Local-first, policy-governed personal CLI agent control layer.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.23.8","commander":"^12.1.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.5","typescript":"^5.7.2","@types/node":"^22.10.0","@vitest/coverage-v8":"^4.1.5"},"_npmOperationalInternal":{"tmp":"tmp/personal-cli-agent_0.1.0_1784171285624_0.6976225757218273","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bin.zhou/personal-cli-agent","version":"0.1.1","description":"Local-first, policy-governed personal CLI agent control layer.","type":"module","engines":{"node":">=20"},"bin":{"agent":"dist/cli/main.js"},"scripts":{"build":"tsc -p tsconfig.json","dev":"node --experimental-strip-types --enable-source-maps src/cli/main.ts","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:ci":"vitest run --coverage","test:security":"vitest run test/security","secret-scan":"vitest run test/security/canary-sweep.test.ts test/security/negative.test.ts","audit":"node scripts/audit-gate.mjs","lint":"tsc --noEmit","sbom":"npm sbom --sbom-format cyclonedx --sbom-type application","prepack":"npm run build","prepublishOnly":"npm run build && npm run typecheck && npm run test:ci && npm run test:security && npm run audit"},"dependencies":{"commander":"^12.1.0","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.10.0","@vitest/coverage-v8":"^4.1.5","typescript":"^5.7.2","vitest":"^4.1.5"},"_id":"@bin.zhou/personal-cli-agent@0.1.1","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-ADDYJxGls1vCwG7rULoz0mVhwWu8WqZ+UevZehYk6qmY4970JbZBj32xs/MBvrlTs+L100yJaecGAGwhFwUAGg==","shasum":"9331ed66f2a1836fa11488528254fad6c82c40ea","tarball":"https://registry.npmjs.org/@bin.zhou/personal-cli-agent/-/personal-cli-agent-0.1.1.tgz","fileCount":280,"unpackedSize":840844,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHgMdCSZpSarD7a+eiFOWIE7telCopycSWbWbQM1DuF1AiA9hQJQibGKY5a10Ce5tKjXxfi+V2YEz827dXNkdzCIZg=="}]},"_npmUser":{"name":"bin.zhou","email":"743028972@qq.com"},"directories":{},"maintainers":[{"name":"bin.zhou","email":"743028972@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/personal-cli-agent_0.1.1_1784174395029_0.9082839340078517"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-16T03:08:05.512Z","modified":"2026-07-16T03:59:55.326Z","0.1.0":"2026-07-16T03:08:05.846Z","0.1.1":"2026-07-16T03:59:55.190Z"},"description":"Local-first, policy-governed personal CLI agent control layer.","maintainers":[{"name":"bin.zhou","email":"743028972@qq.com"}],"readme":"# Personal CLI Agent\n\n> **使用文档 / Usage guide → [USAGE.md](USAGE.md)** — install, config, the two\n> execution flows, memory, diagnostics, troubleshooting, exit codes, safety model.\n\nLocal-first, policy-governed personal CLI agent control layer. The model provider\nis a replaceable, user-authorized reasoning backend — not the owner of the\nworkflow. The user owns local project memory, controlled execution, verification\nevidence, and cost/routing policy.\n\n> Status: P0 complete (M1–M7) + P1 started. Planning + Policy + Execution +\n> + Routing + Memory + Verification are implemented and unit/contract/integration\n> + security-tested; M7 dogfood ran 35 live tasks across 3 private repos (0\n> unauthorized side effects / 0 unredacted secrets / 0 broken audit chains).\n> P1 done: keychain creds, Gemini adapter, local model endpoints, debug summary.\n> High-risk P1 (MCP, auto-push, multi-agent, remote sync) gated behind their own ADRs.\n\n## P0 boundaries (enforced)\n\n- macOS/Linux only; single Git repo; **forced Git worktree** for writes (no `--in-place`).\n- Only compliant user-supplied API keys (OpenAI + Anthropic + Gemini official APIs);\n  a `fake` provider ships for offline/dry-run. No OAuth, cookies, or quota\n  circumvention. Self-hosted OpenAI-compatible / local model endpoints\n  (ollama, vLLM) are opt-in via `allow_local_endpoints` (P1-006).\n- **Policy Gateway is the single entry point for every side effect.** Provider\n  adapters, the planner, memory, and the verifier cannot bypass it; the executor\n  only accepts grants signed by the gateway.\n- **Credentials**: `env:NAME` (process env) and `keychain:NAME` (macOS Keychain\n  via `security` / Linux Secret Service via `secret-tool`; P1, spec 03 §12.2).\n  Resolved values are short-lived, never persisted/printed/audited; absence\n  fails soft (provider excluded with `no_credential`).\n- **Debug summary** (opt-in, `PERSONAL_AGENT_DEBUG_SUMMARY=1`): stores a redacted\n  request/response summary (metadata + token counts + 160-char secret-scrubbed\n  snippets) as an owner-only TTL artifact — never the full prompt/response or key.\n- No MCP, no IDE, no auto-commit/push, no cloud sync in P0 (P1 items needing\n  their own ADR + threat review: see `06-P1-ADR与路线.md`).\n\n## Architecture\n\n```text\ncli/                  commander commands, JSON envelope, exit-code mapping\napplication/          orchestrator (state machine + grant issuance), executor, memory\ndomain/               Task/Plan/EffectProposal/PolicyDecision/Grant/Evidence + state machine\nports/                Provider, Executor, Store, Memory, Audit, Credential, Hash/Clock/Id\npolicy/               risk classifier, path guard, argv guard, redactor, Policy Gateway, grant signer\nrouting/              capability matrix, budget, pre-authorized-only fallback\nplanning/             Plan JSON schema (zod), prompt assembly with provenance, planner\nverification/         evidence assembly + report rendering (text/json/md)\ninfrastructure/\n  persistence/        node:sqlite (WAL) + migrations + SqliteStore\n  audit/              append-only hash-chain audit sink + JSONL export\n  execution/          Git/File/Process/Network adapters (shell:false, realpath containment)\n  providers/          fake + OpenAI + Anthropic + Gemini adapters (fake HTTP transport in tests)\n  secrets/            env: + keychain: (macOS/Linux) credential ports, composite dispatch\nconfig/               minimal TOML parser + layered merge (repo may only tighten)\n```\n\nDependency direction is outward→inward: `cli`/`infrastructure` depend on\n`application`/`domain`/`ports`; `domain` imports no Node SDK, DB, or shell.\n\n## CLI\n\n```bash\nagent                                    # interactive REPL session (like claude/codex): natural-language -> plan -> approve -> execute -> report, multi-turn\nagent init [path]                       # validate git repo, init .personal-agent/, migrate DB\nagent doctor [--json] [--check-provider]   # read-only checks: git, config, schema, providers. --check-provider: declared, policy-gated reachability probe (default OFF; never sends prompts/business data)\nagent run <goal> [--provider] [--budget] [--dry-run] [--yes] [--allow-dirty] [--json]\n                                        # --dry-run: route only. default: plan + stop at approval.\n                                        # --yes: approve all displayed effects, execute+verify+report.\n                                        # dirty working tree is refused unless --allow-dirty (ADR-003).\nagent approve <task-id> <approval-id>  # approve a pending effect (the approval-id is shown by `run`)\nagent execute <task-id>                  # staged: create worktree, execute approved effects, verify, report\nagent resume <task-id>                  # recover a resumable task\nagent status [task-id] [--json]        # task state, budget, last audit seq\nagent report <task-id> [--format text|json|md]   # render the report from stored evidence\nagent audit verify|export [task-id]    # verify the tamper-evident hash chain / export JSONL\nagent cleanup [task-id] [--force]      # remove isolated worktrees for terminal tasks\nagent memory list|add|forget ...\nagent config validate|show\n```\n\nTwo execution flows: `run --yes` (one-shot, in-process) or the staged\n`run` → `approve` (per decision) → `execute`. file.write payloads are persisted\nto an owner-only artifact store keyed by content hash, so `execute` (a separate\nprocess) reconstructs approved content without re-calling the provider.\n\nJSON result envelope: `{ apiVersion:\"v1\", ok, data?, error?, requestId }`. Exit codes\nfollow the spec (0 ok, 2 usage/config, 3 user-action, 4 policy, 5 provider/route,\n6 execution, 7 data/migration, 130 interrupt).\n\n## Install\n\n**Published package (one line, once on npm):**\n```bash\nnpm install -g @bin.zhou/personal-cli-agent\n# or a curl installer:\ncurl -fsSL https://raw.githubusercontent.com/<org>/<repo>/main/packages/personal-cli-agent/scripts/install.sh | sh\n```\n\n**From source (dev / pre-publish):**\n```bash\ncd packages/personal-cli-agent\nnpm install && npm run build && npm link   # puts `agent` on PATH\n```\n\nThen run the interactive first-time setup (picks a provider, stores your key in\nthe OS keychain, writes the config - no hand-editing TOML):\n```bash\nagent setup\n```\n\n`npm publish` is gated by `prepublishOnly` (build + typecheck + coverage-gated\ntests + security regression + `npm audit`), and `prepack` rebuilds `dist/` so the\ntarball always ships a fresh binary. Ship set: `dist/` + `README.md` +\n`USAGE.md` + `UNINSTALL.md` (see `files` in `package.json`).\n\n## Develop\n\n```bash\nnpm install        # workspace install\nnpm run build      # tsc -> dist/\nnpm test           # vitest run (268 tests; E2E gated on MINIMAX_KEY)\nnpm run test:security\n```\n\n**Live E2E** (`test/e2e/cli-flow.e2e.test.ts`, gated on `MINIMAX_KEY`): runs the\nBUILT `dist/cli/main.js` against a disposable git repo with a real provider,\ncovering the full staged flow (`init` → `run`(plan) → `approve` → `execute` →\n`report` → `status` → `audit verify/export` → `cleanup`) plus `--yes`,\n`--dry-run`, `--budget` rejection, `memory add/list/forget`, `resume`, `doctor`,\nand `config`. Asserts worktree isolation, no key leak, audit-chain integrity.\nSkipped without a key (CI runs the 268 deterministic tests).\n\nNode ≥20 (developed on Node 24, using the built-in `node:sqlite` — no native deps).\nConfig dirs: `PERSONAL_AGENT_HOME` (default `~/.personal-cli-agent`) and\n`PERSONAL_AGENT_PROJECT_DIR` (default `<repo>/.personal-agent`).\n\n**Provider fallback (M5):** on a retryable provider failure (rate-limit /\nunavailable / malformed), the orchestrator switches to another pre-authorized,\ncapability-matching candidate within the same budget, auditing the switch reason.\nIt never falls back on non-retryable errors (auth/terms) and never reaches a\nprovider outside the route's surviving candidates.\n\n**Schema safety (10.2):** migrations are forward-only with a pre-migration\nbackup (state.db + WAL/SHM sidecars, restored on failure); `doctor` reports the\nrecent backup. If the DB schema is newer than this app supports, write commands\nfail with `SCHEMA_VERSION_NEWER_THAN_APP` while read-only commands\n(status/report/doctor/audit) still work.\n\nFull product, architecture, interface, and security planning:\n[规划包](../../docs/技术方案/personal-cli-agent/README.md).\n\n## Release artifacts\n\nPer the release gate (04 §6.1), the release package includes an SBOM, the\ndependency lockfile, versioned default policy, and uninstall/data-cleanup\ninstructions:\n\n- **CI gate** — `.github/workflows/ci.yml` runs, on every push/PR: typecheck,\n  build, coverage-gated unit/contract/integration tests, the negative +\n  canary-sweep security regression, a dependency-vulnerability audit, and SBOM\n  generation. (This package is currently a workspace member without its own\n  git remote; the workflow file is ready-to-deploy when it becomes its own\n  repo. Run the same gate locally with:)\n  ```bash\n  npm run typecheck && npm run test:ci && npm run test:security && npm run audit && npm run sbom --silent > sbom.cdx.json\n  ```\n  - `npm run test:ci` — `vitest run --coverage`; enforces the coverage\n    thresholds (statements/lines ≥80, branches ≥75, functions ≥80).\n  - `npm run secret-scan` — the canary-sweep + negative security suite (no\n    secret survives any output surface).\n  - `npm run audit` — `npm audit --omit=dev --audit-level=high` against the\n    official registry (0 high/critical vulnerabilities expected).\n- **SBOM** — `npm run sbom` emits a CycloneDX 1.5 SBOM of type `application`\n  to stdout (108 components in a clean install). Pipe to a file in the release\n  job:\n  ```bash\n  npm run sbom --silent > sbom.cdx.json   # in a clean release install\n  ```\n  The SBOM is generated from the installed dependency tree, so it must be\n  produced in a **clean, isolated install** of this package (`npm ci` of just\n  `@bin.zhou/personal-cli-agent`). A shared monorepo dev install can\n  contain unrelated sibling-package dependency inconsistencies that make\n  `npm sbom` refuse; the release environment is isolated, so this does not\n  apply there.\n- **Lockfile** — ship `package-lock.json`.\n- **Default policy** — `DEFAULT_REPO_CONFIG_TOML` (written by `agent init`).\n- **Uninstall / data cleanup** —\n  [UNINSTALL.md](./UNINSTALL.md).\n","readmeFilename":"README.md"}