@ouro.bot/cli 0.1.0-alpha.287 → 0.1.0-alpha.288

package/changelog.json

@@ -1,6 +1,12 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.288",
+      "changes": [
+        "feat(bundle): full `.gitignore` template + first-push PII review workflow + confirmation-token gate on `bundle_push`. Completes the agent-manages-its-own-bundle chain (PRs 5 + 6 + 7). (1) New `src/repertoire/bundle-templates.ts` exports `BUNDLE_GITIGNORE_TEMPLATE` — a curated gitignore that handles functional cases only (runtime state, credentials, editor/OS noise, build artifacts) and explicitly does NOT block PII. The design philosophy is baked into the file's top-comment: bundles are inherently full of PII (friends/, diary/, journal/, psyche/, arc/, facts/, family/, travel/) and blocking those via gitignore would defeat the bundle's purpose. PII is handled at first-push time by a separate safety layer instead. Also exports `PII_BUNDLE_DIRECTORIES` as the canonical list of PII-bearing top-level dirs. (2) `bundle_init_git` now writes the full template instead of the minimal `state/`-only placeholder from PR 6. (3) New `bundle_first_push_review` tool enumerates existing PII directories with per-directory file counts (honoring `.gitignore` via `git ls-files --others --exclude-standard`), probes the remote URL for GitHub public/private visibility via an unauthenticated `fetch` to `https://api.github.com/repos/{owner}/{repo}` with a 5-second timeout, and generates a first-person warning text — `warningLevel: 'public_github' | 'private_github' | 'generic'`. The tool issues a `confirmationToken` (crypto.randomUUID) stored in a module-level Map with a 15-minute TTL and returns it in the payload. (4) `bundle_push` updated to accept an optional `confirmation_token` parameter: on first-push attempts (detected via `git ls-remote --heads <remote> <branch>` empty — or, conservatively, when that probe fails to reach the remote), the handler requires a valid token that was issued for the SAME bundleRoot and has not expired. Missing, invalid, wrong-bundle, or expired token returns `kind: 'confirmation_required'`. On successful validation, the token is consumed (one-shot). This is the Directive D PII-review gate: the agent cannot push a bundle to the internet without the human explicitly acknowledging the PII payload first. 17 new tests cover the template, PII counting with empty and populated directories, GitHub public/private/404/network-error/malformed-response paths, URL parsing for gitlab/self-hosted/github, token storage + TTL expiry, and every token-gating refusal path in bundle_push. Bundle-templates.ts is added to the file-completeness exempt list since it's a pure constants module (design: `tools-bundle.ts` owns the observability for bundle operations)."
+      ]
+    },
     {
       "version": "0.1.0-alpha.287",
       "changes": [

package/dist/nerves/coverage/file-completeness.js

@@ -71,6 +71,10 @@ const DISPATCH_EXEMPT_PATTERNS = [
     "repertoire/commerce-errors",
     // Log redaction: pure utility consumed by the NDJSON sink (no independent side effects).
     "nerves/redact",
+    // Bundle templates: pure constants (gitignore template string, PII
+    // directory list). No runtime behavior — consumed by tools-bundle.ts
+    // which owns the observability for bundle operations.
+    "repertoire/bundle-templates",
 ];
 function isDispatchExempt(filePath) {
     return DISPATCH_EXEMPT_PATTERNS.some((pattern) => filePath.includes(pattern));

package/dist/repertoire/bundle-templates.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Templates for agent bundle scaffolding.
+ *
+ * ## .gitignore design philosophy
+ *
+ * The bundle .gitignore handles FUNCTIONAL "shouldn't track" cases only:
+ *
+ *   - Runtime state (sessions, logs, runtime files) — stale data with no
+ *     value for review or history.
+ *   - Credentials — real secrets live in `~/.agentsecrets`, but defense
+ *     in depth in case anything leaks into the bundle.
+ *   - Editor / OS noise (.DS_Store, .idea/, etc.).
+ *   - Build artifacts (rare in bundles, but possible).
+ *
+ * It DOES NOT handle PII. The bundle is inherently full of PII — `friends/`,
+ * `diary/`, `journal/`, `psyche/`, `arc/`, `facts/`, `family/`, `travel/`
+ * etc. That's the point of the bundle; blocking those via .gitignore would
+ * defeat the purpose.
+ *
+ * PII is handled at first-push time by `bundle_first_push_review`, which
+ * enumerates PII-bearing directories, shows the agent counts, probes the
+ * remote URL for GitHub visibility, and hard-pauses until the human
+ * confirms. See Directive D in the planning doc.
+ *
+ * No content-pattern blocks (no `**\/sk-ant-*` or similar). Content-review
+ * failures are a different safety layer — credential scanning at commit
+ * time would be a follow-up feature.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PII_BUNDLE_DIRECTORIES = exports.BUNDLE_GITIGNORE_TEMPLATE = void 0;
+exports.BUNDLE_GITIGNORE_TEMPLATE = `# Runtime state — sessions, logs, runtime files, never tracked
+state/
+
+# Credentials — never tracked. Real secrets live in ~/.agentsecrets, but
+# defense in depth in case anything leaks into the bundle.
+.env
+.env.*
+secrets/
+**/*.key
+**/*.pem
+**/*.credentials
+**/*.pfx
+
+# Editor and OS noise
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Build artifacts (rare in bundles, but possible if a workspace lands here)
+node_modules/
+dist/
+`;
+/**
+ * PII-sensitive top-level directories. Enumerated here so `bundle_first_push_review`
+ * can categorize and count. Adding a new PII bucket to the bundle means adding
+ * it here so the first-push warning includes it.
+ */
+exports.PII_BUNDLE_DIRECTORIES = [
+    "friends",
+    "diary",
+    "journal",
+    "psyche",
+    "arc",
+    "facts",
+    "family",
+    "travel",
+    "memory",
+    "sessions",
+];

package/dist/repertoire/tools-bundle.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bundleToolDefinitions = void 0;
+exports.__getConfirmationTokenStore = __getConfirmationTokenStore;
 /**
  * Agent-callable bundle management tools.
  *
@@ -71,11 +72,13 @@ exports.bundleToolDefinitions = void 0;
  * calls `bundle_list_first_commit` and stages each entry individually.
  */
 const child_process_1 = require("child_process");
+const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const runtime_1 = require("../nerves/runtime");
 const identity_1 = require("../heart/identity");
 const bundle_state_1 = require("../heart/bundle-state");
+const bundle_templates_1 = require("./bundle-templates");
 function gitExec(bundleRoot, args, timeoutMs = 10000) {
     try {
         const stdout = (0, child_process_1.execFileSync)("git", args, {
@@ -252,12 +255,14 @@ const initGitHandler = (args) => {
         }
         /* v8 ignore stop */
     }
-    // Write minimal .gitignore template if one doesn't already exist.
-    // PR 7 extends this with the full PII-safe template.
+    // Write the full .gitignore template if one doesn't already exist.
+    // See BUNDLE_GITIGNORE_TEMPLATE's design philosophy: functional blocks
+    // only (credentials, state, noise, build artifacts); PII is handled
+    // separately by bundle_first_push_review at first-push time.
     const gitignorePath = path.join(bundleRoot, ".gitignore");
     let gitignoreWritten = false;
     if (!fs.existsSync(gitignorePath)) {
-        fs.writeFileSync(gitignorePath, "state/\n", "utf-8");
+        fs.writeFileSync(gitignorePath, bundle_templates_1.BUNDLE_GITIGNORE_TEMPLATE, "utf-8");
         gitignoreWritten = true;
     }
     const result = { ok: true, alreadyInit, gitignoreWritten };
@@ -489,6 +494,155 @@ const doFirstCommitHandler = (args) => {
     const commitSha = rev.stdout.trim();
     return finish(true, { commitSha, fileCount: filesToStage.length, message });
 };
+const CONFIRMATION_TOKEN_TTL_MS = 15 * 60 * 1000;
+const _confirmationTokens = new Map();
+function pruneExpiredTokens(now) {
+    for (const [token, entry] of _confirmationTokens) {
+        if (now - entry.createdAt > CONFIRMATION_TOKEN_TTL_MS) {
+            _confirmationTokens.delete(token);
+        }
+    }
+}
+/** Test hook: lets unit tests inspect + clear the token store. */
+function __getConfirmationTokenStore() {
+    return _confirmationTokens;
+}
+function countFilesInDir(bundleRoot, relDir) {
+    // Use `git ls-files --others --exclude-standard -- <dir>` to honor .gitignore.
+    const result = gitExec(bundleRoot, ["ls-files", "--others", "--exclude-standard", "--", relDir]);
+    /* v8 ignore next -- git ls-files failure requires a corrupt repo @preserve */
+    if (result.code !== 0)
+        return 0;
+    return result.stdout.split("\n").filter((l) => l.trim().length > 0).length;
+}
+function parseGitHubUrl(url) {
+    // https://github.com/owner/repo(.git)
+    const httpsMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(\.git)?$/);
+    if (httpsMatch)
+        return { owner: httpsMatch[1], repo: httpsMatch[2] };
+    // git@github.com:owner/repo(.git)
+    const sshMatch = url.match(/^git@github\.com:([^/]+)\/([^/]+?)(\.git)?$/);
+    if (sshMatch)
+        return { owner: sshMatch[1], repo: sshMatch[2] };
+    return null;
+}
+async function checkGitHubVisibility(parsed, fetchFn) {
+    const controller = new AbortController();
+    /* v8 ignore next -- 5-second timeout abort only fires if fetch takes longer than the test runner allows; the abort path is defensive @preserve */
+    const timer = setTimeout(() => controller.abort(), 5000);
+    try {
+        const res = await fetchFn(`https://api.github.com/repos/${parsed.owner}/${parsed.repo}`, {
+            signal: controller.signal,
+            headers: { Accept: "application/vnd.github+json" },
+        });
+        if (!res.ok)
+            return "unknown";
+        const data = (await res.json());
+        if (data.private === true)
+            return "private";
+        if (data.private === false)
+            return "public";
+        /* v8 ignore next -- malformed GitHub API response (private field neither true nor false) is not practical to provoke @preserve */
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function makeFirstPushReviewHandler(deps = {}) {
+    return async () => {
+        const bundleRoot = (0, identity_1.getAgentRoot)();
+        const fetchFn = deps.fetch ?? globalThis.fetch;
+        const now = deps.now ?? Date.now;
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.bundle_first_push_review_start",
+            message: "reviewing bundle for first push",
+            meta: { bundleRoot },
+        });
+        const finish = (ok, payload) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.bundle_first_push_review_end",
+                message: "bundle_first_push_review finished",
+                meta: { bundleRoot, ok, ...payload },
+            });
+            return json({ ok, ...payload });
+        };
+        if (!isGitRepo(bundleRoot)) {
+            return finish(false, { error: "bundle is not a git repo — run bundle_init_git first" });
+        }
+        const remotes = listRemotes(bundleRoot);
+        if (remotes.length === 0) {
+            return finish(false, { error: "no remote configured — run bundle_add_remote first" });
+        }
+        const remoteName = remotes[0];
+        const remoteUrl = getRemoteUrl(bundleRoot, remoteName);
+        /* v8 ignore next 3 -- listRemotes returned a name but get-url failed; only possible under a git race @preserve */
+        if (!remoteUrl) {
+            return finish(false, { error: "could not resolve remote url" });
+        }
+        // Enumerate PII directory counts
+        const piiCounts = {};
+        let totalPiiRecords = 0;
+        for (const dir of bundle_templates_1.PII_BUNDLE_DIRECTORIES) {
+            const dirPath = path.join(bundleRoot, dir);
+            if (!fs.existsSync(dirPath))
+                continue;
+            const count = countFilesInDir(bundleRoot, dir);
+            if (count > 0) {
+                piiCounts[dir] = count;
+                totalPiiRecords += count;
+            }
+        }
+        // GitHub visibility probe
+        const parsedGitHub = parseGitHubUrl(remoteUrl);
+        let warningLevel = "generic";
+        if (parsedGitHub) {
+            const visibility = await checkGitHubVisibility(parsedGitHub, fetchFn);
+            if (visibility === "public")
+                warningLevel = "public_github";
+            else if (visibility === "private")
+                warningLevel = "private_github";
+        }
+        // Build first-person warning text
+        const piiSummary = Object.entries(piiCounts)
+            .map(([dir, count]) => `${count} ${dir} record${count === 1 ? "" : "s"}`)
+            .join(", ");
+        const piiClause = piiSummary.length > 0
+            ? `my bundle contains personal data: ${piiSummary} (${totalPiiRecords} records total)`
+            : "my bundle has no PII directories populated yet";
+        let visibilityClause;
+        if (warningLevel === "public_github") {
+            visibilityClause = `⚠️  ${remoteUrl} is a PUBLIC GitHub repo — anything i push will be visible to anyone. are you SURE you want to push PII to a public repo?`;
+        }
+        else if (warningLevel === "private_github") {
+            visibilityClause = `${remoteUrl} is a PRIVATE GitHub repo. still, confirm you want to push this data there.`;
+        }
+        else {
+            visibilityClause = `${remoteUrl} — i can't verify this remote's visibility. confirm the repo is private before i push PII.`;
+        }
+        const warningText = `${piiClause}. ${visibilityClause}`;
+        // Issue and store the confirmation token
+        const token = crypto.randomUUID();
+        const currentTime = now();
+        pruneExpiredTokens(currentTime);
+        _confirmationTokens.set(token, { bundleRoot, createdAt: currentTime });
+        return finish(true, {
+            warningLevel,
+            remoteUrl,
+            piiCounts,
+            totalPiiRecords,
+            warningText,
+            confirmRequired: true,
+            confirmationToken: token,
+        });
+    };
+}
+const firstPushReviewHandler = makeFirstPushReviewHandler();
 // ─── tool: bundle_push ─────────────────────────────────────────────────
 /* v8 ignore start -- push error classification branches require mocking git stderr from each failure mode; covered by a single network-failure integration test in the suite @preserve */
 function classifyPushError(stderr) {
@@ -502,43 +656,130 @@ function classifyPushError(stderr) {
     return "unknown";
 }
 /* v8 ignore stop */
-const pushHandler = (args) => {
-    const bundleRoot = (0, identity_1.getAgentRoot)();
-    const remote = typeof args.remote === "string" && args.remote.length > 0 ? args.remote : "origin";
-    (0, runtime_1.emitNervesEvent)({
-        component: "repertoire",
-        event: "repertoire.bundle_push_start",
-        message: "pushing bundle to remote",
-        meta: { bundleRoot, remote },
-    });
-    const finish = (ok, payload) => {
+/**
+ * Detect whether this is a first push to the remote.
+ *
+ * Returns true if the remote branch does not yet exist (bundle has local
+ * commits but has never been pushed). Also returns true — conservatively —
+ * when git fails to probe the remote (network unreachable, git error).
+ * The token requirement is a security gate; if we can't verify the remote
+ * state, we assume the worst and force the agent to get confirmation. An
+ * unreachable remote should NOT be a bypass vector.
+ */
+/* v8 ignore start -- isFirstPushToRemote has two branches that only differ when the remote is reachable; in the unit test environment all remotes are unreachable so we always hit the "return true on network failure" branch. The security contract (never return false when unsure) is covered by the refusal tests in bundle-first-push-review.test.ts @preserve */
+function isFirstPushToRemote(bundleRoot, remote) {
+    const branchResult = gitExec(bundleRoot, ["symbolic-ref", "--short", "HEAD"]);
+    if (branchResult.code !== 0)
+        return true;
+    const branch = branchResult.stdout.trim();
+    const lsRemote = gitExec(bundleRoot, ["ls-remote", "--heads", remote, branch], 10000);
+    if (lsRemote.code !== 0)
+        return true;
+    return lsRemote.stdout.trim().length === 0;
+}
+/* v8 ignore stop */
+function makePushHandler(deps = {}) {
+    return (args) => {
+        const bundleRoot = (0, identity_1.getAgentRoot)();
+        const remote = typeof args.remote === "string" && args.remote.length > 0 ? args.remote : "origin";
+        const confirmationToken = typeof args.confirmation_token === "string"
+            ? args.confirmation_token
+            : undefined;
+        const now = deps.now ?? Date.now;
         (0, runtime_1.emitNervesEvent)({
             component: "repertoire",
-            event: "repertoire.bundle_push_end",
-            message: "bundle_push finished",
-            meta: { bundleRoot, ok, ...payload },
+            event: "repertoire.bundle_push_start",
+            message: "pushing bundle to remote",
+            meta: { bundleRoot, remote },
         });
-        return json({ ok, ...payload });
+        const finish = (ok, payload) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.bundle_push_end",
+                message: "bundle_push finished",
+                meta: { bundleRoot, ok, ...payload },
+            });
+            return json({ ok, ...payload });
+        };
+        if (!isGitRepo(bundleRoot)) {
+            return finish(false, { error: "bundle is not a git repo" });
+        }
+        const remotes = listRemotes(bundleRoot);
+        if (!remotes.includes(remote)) {
+            return finish(false, { error: `remote "${remote}" not configured — run bundle_add_remote first` });
+        }
+        if (!hasHead(bundleRoot)) {
+            return finish(false, { error: "bundle has no commits — run bundle_do_first_commit first" });
+        }
+        // Directive D: first push to a remote requires the agent to have
+        // previously called bundle_first_push_review and obtained a
+        // confirmation token. This forces a PII-review gate between
+        // "bundle built locally" and "bundle contents on the internet".
+        const isFirstPush = isFirstPushToRemote(bundleRoot, remote);
+        /* v8 ignore next -- the !isFirstPush branch (subsequent push path) requires a reachable remote to test end-to-end; the path itself falls through to the git push below which is covered by the network-failure test @preserve */
+        if (isFirstPush) {
+            if (!confirmationToken) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "repertoire",
+                    event: "repertoire.bundle_push_refused",
+                    message: "bundle_push refused: first push requires confirmation token",
+                    meta: { bundleRoot },
+                });
+                return finish(false, {
+                    error: "refused: first push requires a confirmation token — call bundle_first_push_review, show the warning to the user, and pass the returned confirmationToken to bundle_push",
+                    kind: "confirmation_required",
+                });
+            }
+            const currentTime = now();
+            pruneExpiredTokens(currentTime);
+            const entry = _confirmationTokens.get(confirmationToken);
+            if (!entry) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "repertoire",
+                    event: "repertoire.bundle_push_refused",
+                    message: "bundle_push refused: confirmation token invalid or expired",
+                    meta: { bundleRoot },
+                });
+                return finish(false, {
+                    error: "refused: confirmation token invalid or expired — call bundle_first_push_review again",
+                    kind: "confirmation_required",
+                });
+            }
+            if (entry.bundleRoot !== bundleRoot) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "repertoire",
+                    event: "repertoire.bundle_push_refused",
+                    message: "bundle_push refused: confirmation token bound to a different bundle",
+                    meta: { bundleRoot, tokenBundleRoot: entry.bundleRoot },
+                });
+                return finish(false, {
+                    error: "refused: confirmation token was issued for a different bundle",
+                    kind: "confirmation_required",
+                });
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.bundle_push_first_push_confirmed",
+                message: "first push confirmed by valid token",
+                meta: { bundleRoot },
+            });
+            // One-shot: consume the token on successful validation.
+            _confirmationTokens.delete(confirmationToken);
+        }
+        const push = gitExec(bundleRoot, ["push", remote, "HEAD"], 30000);
+        /* v8 ignore start -- push success branch requires a reachable remote, not practical to cover in unit tests; failure branch covered by network-failure test @preserve */
+        if (push.code === 0) {
+            return finish(true, { remote, firstPush: isFirstPush });
+        }
+        /* v8 ignore stop */
+        const kind = classifyPushError(push.stderr);
+        return finish(false, { error: push.stderr.trim(), kind });
     };
-    if (!isGitRepo(bundleRoot)) {
-        return finish(false, { error: "bundle is not a git repo" });
-    }
-    const remotes = listRemotes(bundleRoot);
-    if (!remotes.includes(remote)) {
-        return finish(false, { error: `remote "${remote}" not configured — run bundle_add_remote first` });
-    }
-    if (!hasHead(bundleRoot)) {
-        return finish(false, { error: "bundle has no commits — run bundle_do_first_commit first" });
-    }
-    const push = gitExec(bundleRoot, ["push", remote, "HEAD"], 30000);
-    /* v8 ignore start -- push success branch requires a reachable remote, not practical to cover in unit tests; failure branch covered by network-failure test @preserve */
-    if (push.code === 0) {
-        return finish(true, { remote });
-    }
-    /* v8 ignore stop */
-    const kind = classifyPushError(push.stderr);
-    return finish(false, { error: push.stderr.trim(), kind });
-};
+}
+const pushHandler = makePushHandler();
 // ─── tool: bundle_pull_rebase ──────────────────────────────────────────
 const pullRebaseHandler = (args) => {
     const bundleRoot = (0, identity_1.getAgentRoot)();
@@ -689,16 +930,28 @@ exports.bundleToolDefinitions = [
         },
         handler: doFirstCommitHandler,
     },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "bundle_first_push_review",
+                description: "Review my bundle for PII exposure before the first push to a new remote. Enumerates PII-bearing directories (friends, diary, journal, etc.) with per-directory counts, probes the remote URL for GitHub public/private visibility, and returns a first-person warning text I must show the human plus a confirmationToken I must pass to bundle_push on first push. Required before the first push to any new remote.",
+                parameters: { type: "object", properties: {} },
+            },
+        },
+        handler: firstPushReviewHandler,
+    },
     {
         tool: {
             type: "function",
             function: {
                 name: "bundle_push",
-                description: "Push my bundle's HEAD to the configured remote. Returns a structured error with kind: 'rejected' | 'network' | 'auth' | 'unknown' on failure. Does NOT auto-rebase on rejection — use bundle_pull_rebase explicitly when needed.",
+                description: "Push my bundle's HEAD to the configured remote. On first push to a new remote, requires a confirmation_token from bundle_first_push_review (Directive D: human must acknowledge PII exposure before the bundle goes over the wire). Subsequent pushes ignore the token. Returns a structured error with kind: 'rejected' | 'network' | 'auth' | 'unknown' | 'confirmation_required' on failure. Does NOT auto-rebase on rejection — use bundle_pull_rebase explicitly when needed.",
                 parameters: {
                     type: "object",
                     properties: {
                         remote: { type: "string", description: "Remote name. Defaults to 'origin'." },
+                        confirmation_token: { type: "string", description: "Opaque token from bundle_first_push_review. Required on the first push to a new remote; ignored on subsequent pushes." },
                     },
                 },
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.287",
+  "version": "0.1.0-alpha.288",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",