threadroot 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to Threadroot will be documented here.
 
 Threadroot follows semantic versioning after the first public release. While `0.x`, minor versions may include breaking changes as the harness format settles.
 
+## 0.1.5 - Website integration contracts
+
+### Added
+
+- `bootstrap --packs <list>` to install capability packs during first-run setup.
+- Machine-readable `--json` output for `bootstrap`, `start`, `status`, `context`, `doctor`, `mcp check`, and `mcp setup`.
+- Connection authoring flags for `--allow` and `--deny` command fragments.
+- `INTEGRATION.md` as the website/cloud contract for prompt generation, JSON CLI usage, and future auth/sync shape.
+
+### Changed
+
+- MCP tool calls now return structured content alongside text content.
+- MCP `tools_run` no longer accepts model-supplied confirmation for risky tools; agents must ask the user to approve via the CLI.
+- Connection `allow` and `deny` rules are enforced when connection-backed shell tools run.
+- Pack installs now write object-level provenance and sha256 integrity entries to `.threadroot/lock.json`.
+- Release guidance now points toward npm provenance and signature verification.
+
+## 0.1.4 - Stable npx MCP config
+
+### Fixed
+
+- `bootstrap --mcp` and `setup --global --mcp` now detect npm's `_npx` cache path and write a stable pinned `npx --yes threadroot@<version> mcp` Codex MCP command instead of pointing Codex at a transient npm cache file.
+
 ## 0.1.3 - Verified Codex MCP setup
 
 ### Added

package/INTEGRATION.md

@@ -0,0 +1,256 @@
+# Threadroot Integration Contract
+
+This document is the handoff surface for a future website, prompt generator, and
+cloud/auth repo. The OSS CLI remains the source of truth. The website should
+generate prompts and commands that drive this CLI instead of reimplementing
+harness logic.
+
+## Product Boundary
+
+Threadroot OSS is the local agent harness compiler:
+
+- `.threadroot/` is canonical project state.
+- The CLI initializes, validates, compiles, and exposes harness context.
+- MCP exposes the same local harness to agent clients.
+- Tools and connections execute locally only.
+- No secrets are stored in the repo.
+
+The website/cloud repo can add:
+
+- Prompt generation for new/existing projects.
+- Account login, repo/project bindings, and saved project preferences.
+- Cloud-hosted skill, pack, and tool authoring workflows.
+- Optional sync of approved harness objects into a local repo.
+
+The website/cloud repo must not bypass the local CLI trust model for execution.
+
+## Website Prompt Generator Inputs
+
+The website should ask for a small set of high-signal choices:
+
+- Project state: `new`, `existing`, or `existing-with-agent-files`.
+- Primary agent/provider: `codex`, `claude`, `cursor`, `copilot`, `gemini`,
+  `windsurf`, `antigravity`, `opencode`, or `all`.
+- IDE/editor: VS Code, Cursor, terminal-only, other.
+- Project profile: `nextjs`, `vite-react`, `fastapi`, `python-cli`,
+  `node-cli`, `dbt`, or `empty`.
+- Stack tags: TypeScript, React, Python, testing, security, system design,
+  CLI, data, cloud.
+- Cloud/tooling needs: GitHub, AWS, Azure, Snowflake, dbt, none.
+- Initial task: a short natural language task.
+- Project clutter preference: local-only default, optional provider exposure.
+- MCP preference: configure Codex MCP now, project-local MCP later, or skip.
+
+## Prompt-to-CLI Mapping
+
+The website should prefer one bootstrap command plus verification:
+
+```bash
+threadroot bootstrap --yes \
+  --agent <agent-or-all> \
+  --profile <profile> \
+  --task "<initial task>" \
+  --packs <comma-separated-packs> \
+  --mcp \
+  --json
+```
+
+Use `--no-import` for a blank/new repo when the user wants a clean start:
+
+```bash
+threadroot bootstrap --yes --no-import --profile empty --task "start this project" --json
+```
+
+Use import for an existing repo so Threadroot can preserve useful existing
+agent/vendor context:
+
+```bash
+threadroot bootstrap --yes --profile <profile> --task "<task>" --json
+```
+
+Provider-native project files stay opt-in:
+
+```bash
+threadroot expose <agent>
+```
+
+Verification commands:
+
+```bash
+threadroot doctor --json
+threadroot status --json
+threadroot context "<task>" --json
+threadroot mcp check --json
+```
+
+The success message generated by the website prompt should be:
+
+```text
+Success: Threadroot is ready. Run threadroot start "<task>" for future sessions.
+```
+
+## Pack Mapping
+
+Initial pack choices should map conservatively:
+
+| User choice | Packs |
+| --- | --- |
+| TypeScript or Node CLI | `typescript-node` |
+| React app | `react-app`, `testing` |
+| Python | `python`, `testing` |
+| Testing-heavy project | `testing` |
+| Code review / PR workflow | `code-review` |
+| Security work | `security-review` |
+| Architecture / product planning | `system-design` |
+
+If uncertain, install fewer packs. Agents can list and install more later:
+
+```bash
+threadroot packs list --json
+threadroot packs inspect <pack> --json
+threadroot packs install <pack> --json
+```
+
+Pack installs record object-level provenance in `.threadroot/lock.json` with
+`source: pack:<name>` and sha256 integrity.
+
+## JSON Surfaces
+
+The website/cloud repo should call these commands instead of scraping text:
+
+```bash
+threadroot bootstrap --json
+threadroot start "<task>" --json
+threadroot status --json
+threadroot doctor --json
+threadroot context "<task>" --json
+threadroot mcp check --json
+threadroot mcp setup --json
+threadroot skills list --json
+threadroot skills inspect <path> --json
+threadroot skills validate --json
+threadroot tools list --json
+threadroot tools detect --json
+threadroot tools check --json
+threadroot connections list --json
+threadroot connections check --json
+threadroot packs list --json
+threadroot packs inspect <pack> --json
+threadroot packs validate <pack> --json
+threadroot packs install <pack> --json
+```
+
+Until `1.0`, these JSON shapes are alpha contracts. The website should parse
+only fields it uses and tolerate extra fields.
+
+## Tools And Connections
+
+Tool creation should stay local and explicit:
+
+```bash
+threadroot tools create \
+  --from-command "pnpm test" \
+  --description "Run the test suite" \
+  --risk low \
+  --healthcheck "pnpm test" \
+  --json
+```
+
+Connection creation should wrap official local CLIs only:
+
+```bash
+threadroot connections add aws-dev \
+  --provider aws \
+  --command aws \
+  --profile dev \
+  --risk high \
+  --confirm \
+  --allow "sts get-caller-identity,s3 ls,logs tail" \
+  --deny "delete,terminate,iam" \
+  --healthcheck "aws sts get-caller-identity --profile dev" \
+  --json
+```
+
+Rules:
+
+- Connections must not store credentials.
+- Users authenticate through official CLIs such as `gh`, `aws`, `az`, or
+  Snowflake CLI.
+- MCP cannot self-confirm risky tool execution.
+- High-risk, untrusted, or blocked tools must be approved through the local CLI.
+
+## Future Cloud/Auth CLI Contract
+
+Do not implement these in OSS until the cloud repo exists, but reserve the shape:
+
+```bash
+threadroot login
+threadroot auth status --json
+threadroot link --repo owner/name --project <project-id>
+threadroot sync status --json
+threadroot sync pull --json
+threadroot sync push --json
+threadroot sync apply --from cloud --json
+```
+
+Expected cloud files, if added later:
+
+```text
+.threadroot/cloud.json       # repo binding, no secrets
+~/.threadroot/auth.json      # local auth cache or pointer, never committed
+```
+
+`.threadroot/cloud.json` should contain only non-secret metadata:
+
+```json
+{
+  "version": 1,
+  "projectId": "trp_...",
+  "repo": "owner/name",
+  "remote": "https://api.threadroot.dev"
+}
+```
+
+The auth flow should use device/browser login for CLI users and store tokens
+outside the repository. Repo sync should operate on harness objects, not source
+code, and should always show a diff or status before applying remote changes.
+
+## Cloud Data Model Sketch
+
+Minimum useful entities:
+
+- User
+- Organization
+- RepoBinding
+- CloudProject
+- HarnessSnapshot
+- Skill
+- ToolTemplate
+- ConnectionTemplate
+- Pack
+- InstallEvent
+- AuditEvent
+
+Store generated skills/tools/packs as versioned artifacts. Do not store local CLI
+secrets, cloud provider keys, or repo source code in v1 cloud.
+
+## Security And Release Anchors
+
+- Prefer npm trusted publishing/provenance for package releases.
+- Keep `.threadroot/lock.json` as the local provenance ledger.
+- Treat MCP tools as agent-controlled and require human approval for sensitive
+  actions.
+- Prefer explicit allow/deny policies for connection-backed tools.
+- Keep website-generated prompts short and command-driven.
+- Use `threadroot doctor --json` as the machine-readable trust gate.
+
+## Website Readiness Checklist
+
+The OSS core is ready for website work when:
+
+- `pnpm release:check` passes.
+- `threadroot bootstrap --yes --packs <list> --json` initializes a temp repo.
+- `threadroot doctor --json` reports `ok: true` or actionable findings.
+- Pack installs write `.threadroot/lock.json` provenance.
+- MCP check verifies the local stdio server.
+- README and generated agent prompts reference only real commands.

package/README.md

@@ -39,6 +39,7 @@ node dist/index.js --help
 ```bash
 tr bootstrap --yes      # one-time machine setup + local-only .threadroot/
 tr bootstrap --yes --mcp # also configure and verify global Codex MCP
+tr bootstrap --yes --packs testing,typescript-node
 tr start "write tests"  # doctor, status, relevant context, and command map
 tr mcp check            # verify Codex MCP config and server handshake
 tr expose codex         # optional: write a thin project skill shim for Codex
@@ -49,32 +50,32 @@ tr expose codex         # optional: write a thin project skill shim for Codex
 ## CLI surface
 
 ```bash
-tr bootstrap [--yes] [--agent <list>] [--task <task>] [--mcp] [--expose <list>]
-tr start ["<task>"]
+tr bootstrap [--yes] [--agent <list>] [--task <task>] [--mcp] [--expose <list>] [--packs <list>] [--json]
+tr start ["<task>"] [--json]
 tr setup --global [--agent <list>] [--dry-run] [--check] [--undo] [--mcp]
 tr init [--force] [--no-import] [--profile <p>] [--adapters <list>] [--expose <list>]
 tr expose [agent|all] [--dry-run] [--check] [--undo] [--force]
-tr status
+tr status [--json]
 tr diff
-tr doctor
+tr doctor [--json]
 tr compile [--adapter <agents|claude|copilot|cursor>]
-tr context "<task>"               # assemble the task-relevant harness slice
-tr run <tool> [--input k=v ...] [-y]
+tr context "<task>" [--json]       # assemble the task-relevant harness slice
+tr run <tool> [--input k=v ...] [-y] [--json]
 tr install <source> [--kind skill|tool|rule|connection] [--path <p>] [--user]
 tr remember "<note>" [--type project|current-focus|handoff|pitfalls]
 tr memory read <type>
 tr memory append <type> "<note>"
-tr skills list | validate [--path <path>]
-tr skills inspect <path>
-tr tools list | detect | check
-tr tools add <name> --description "<text>" [--run "<cmd>"]
-tr tools create --from-command "<cmd>"
-tr connections list | check
-tr connections add <name> --provider <p> --command <cmd>
-tr packs list | inspect <pack> | validate <pack> | install <pack>
+tr skills list [--json] | validate [--path <path>] [--json]
+tr skills inspect <path> [--json]
+tr tools list | detect | check [--json]
+tr tools add <name> --description "<text>" [--run "<cmd>"] [--json]
+tr tools create --from-command "<cmd>" [--json]
+tr connections list | check [--json]
+tr connections add <name> --provider <p> --command <cmd> [--allow <patterns>] [--deny <patterns>] [--json]
+tr packs list | inspect <pack> | validate <pack> | install <pack> [--json]
 tr mcp                            # run the local MCP server (stdio)
-tr mcp check                      # verify Codex MCP config and required tools
-tr mcp setup [--write]            # wire MCP into agents
+tr mcp check [--json]             # verify Codex MCP config and required tools
+tr mcp setup [--write] [--json]   # wire MCP into agents
 ```
 
 ## The harness (`.threadroot/`)
@@ -109,10 +110,12 @@ tr start "current task"
 
 Without `--yes`, `tr bootstrap` prints a dry-run plan. With `--yes`, it installs global
 agent bootstrap skills, initializes `.threadroot/` if needed, runs doctor, and prints
-task context. With `--mcp`, it also writes Codex MCP config using the current CLI entry
-(`node /path/dist/index.js mcp` when Threadroot can resolve the package path, or
-`threadroot mcp` as a fallback) and verifies the stdio server handshake. It does not write
-provider-specific project files unless you pass `--expose`.
+task context. With `--mcp`, it also writes Codex MCP config using a durable command for
+the current launch path. `npx` runs write a pinned `npx --yes threadroot@<version> mcp`
+command instead of a transient npm cache path; local dev runs use
+`node /path/dist/index.js mcp`; unknown launch paths fall back to `threadroot mcp`. The
+setup verifies the stdio server handshake. It does not write provider-specific project
+files unless you pass `--expose`.
 
 Global setup installs a tiny `threadroot` skill into supported agent user-skill
 directories so agents know to call `threadroot bootstrap --yes` when setup is missing
@@ -150,7 +153,8 @@ every Threadroot skill into provider directories.
   add-test, debug-failure, write-docs, conventional-commits.
 - **Starter tools:** wrapped from the repo's detected command surface (scripts, Make/just),
   auto-added to `tools.allow`.
-- **Profile presets:** node-cli, web, python, etc. (detected by the scanner).
+- **Profile presets:** `nextjs`, `vite-react`, `fastapi`, `python-cli`, `node-cli`,
+  `dbt`, and `empty` (detected by the scanner or set with `--profile`).
 - **Adapters:** disabled by default to keep new repos local-only; use `tr expose` for
   skill-compatible providers or `tr compile --adapter <name>` for legacy instruction
   files.
@@ -200,6 +204,8 @@ tr connections add aws-dev \
   --profile dev \
   --risk high \
   --confirm \
+  --allow "sts get-caller-identity,s3 ls,logs tail" \
+  --deny "delete,terminate,iam" \
   --healthcheck "aws sts get-caller-identity --profile dev"
 tr connections check
 ```
@@ -251,6 +257,10 @@ Tools: `context`, `skills_list`, `skills_get`, `tools_list`, `tools_check`, `too
 `tools_create`, `tools_detect`, `connections_list`, `connections_check`, `memory_read`,
 `memory_append`, `status`, `doctor`.
 
+MCP can run tools that are already safe under the harness policy. It cannot self-confirm
+`confirm:true`, high-risk, untrusted, or connection-policy-blocked tools; agents should ask
+the user to run `threadroot run <tool> --yes` after review.
+
 `tr mcp setup` also prints a copy/paste agent prompt that follows the real CLI flow:
 check availability, run `threadroot bootstrap --yes`, run `threadroot start "<task>"`,
 and ask before writing project-local MCP config.
@@ -272,6 +282,12 @@ pnpm test
 pnpm build
 ```
 
+## Website and cloud integration
+
+The public CLI is the stable foundation for the private website/cloud repo. See
+[INTEGRATION.md](./INTEGRATION.md) for the prompt-generator contract, JSON command
+surface, future auth/sync shape, and cloud data model sketch.
+
 ## Publishing
 
 The npm package ships only `dist/`, `skills/`, `packs/`, and package metadata. Before
@@ -297,12 +313,13 @@ THREADROOT_ROOT="$(pwd)"
 TMP_REPO="$(mktemp -d /tmp/threadroot-smoke.XXXXXX)"
 rsync -a --exclude .git --exclude node_modules --exclude dist ./ "$TMP_REPO/"
 cd "$TMP_REPO"
-HOME="$TMP_REPO/home" node "$THREADROOT_ROOT/dist/index.js" bootstrap --yes --agent codex --mcp --no-import
-HOME="$TMP_REPO/home" node "$THREADROOT_ROOT/dist/index.js" mcp check
-HOME="$TMP_REPO/home" node "$THREADROOT_ROOT/dist/index.js" start "write tests"
+HOME="$TMP_REPO/home" node "$THREADROOT_ROOT/dist/index.js" bootstrap --yes --agent codex --mcp --no-import --packs testing --json
+HOME="$TMP_REPO/home" node "$THREADROOT_ROOT/dist/index.js" mcp check --json
+HOME="$TMP_REPO/home" node "$THREADROOT_ROOT/dist/index.js" start "write tests" --json
 node "$THREADROOT_ROOT/dist/index.js" expose codex
 node "$THREADROOT_ROOT/dist/index.js" status
 node "$THREADROOT_ROOT/dist/index.js" context "write tests"
+node "$THREADROOT_ROOT/dist/index.js" context "write tests" --json
 node "$THREADROOT_ROOT/dist/index.js" skills validate
 node "$THREADROOT_ROOT/dist/index.js" skills validate --path skills
 node "$THREADROOT_ROOT/dist/index.js" skills inspect skills/system-design
@@ -310,7 +327,7 @@ node "$THREADROOT_ROOT/dist/index.js" packs list
 node "$THREADROOT_ROOT/dist/index.js" packs inspect testing
 node "$THREADROOT_ROOT/dist/index.js" tools create --from-command "node --version" --description "Check Node.js"
 node "$THREADROOT_ROOT/dist/index.js" tools check
-node "$THREADROOT_ROOT/dist/index.js" connections add node-local --provider node --command node --risk low --healthcheck "node --version"
+node "$THREADROOT_ROOT/dist/index.js" connections add node-local --provider node --command node --risk low --allow "--version" --deny "rm,delete" --healthcheck "node --version"
 node "$THREADROOT_ROOT/dist/index.js" connections check
 node "$THREADROOT_ROOT/dist/index.js" compile
 node "$THREADROOT_ROOT/dist/index.js" diff