@nac3/forge-cli 0.2.0-alpha.1

package/dist/chat/tools/github.js

@@ -0,0 +1,310 @@
+/**
+ * GitHub tools wired into the chat catalog (V1.11 of HITO 1).
+ *
+ * Three tools land in this slice:
+ *   - forge.create_github_repo(name, private?)
+ *   - forge.clone_repo(url, target_dir?)
+ *   - forge.branch_status(repo_dir)
+ *
+ * Vault slot: `github_token` (Personal Access Token with
+ * `repo` scope -- needed for both create + private clone).
+ *
+ * Auth is server-side only -- the token never crosses to the
+ * browser. The clone tool uses git CLI under the hood with
+ * the token spliced into the URL only at the spawn boundary;
+ * the spawned process inherits no env var with the token.
+ *
+ * Loud failures per ROADMAP sec 12.2:
+ *   - Missing vault slot -> hard error citing slot + `yf vault
+ *     set github_token`.
+ *   - HTTP non-2xx -> hard error with status + body snippet.
+ *   - git CLI missing or non-zero exit -> hard error with
+ *     stderr.
+ *
+ * ASCII-only.
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { Vault } from '../../vault/store.js';
+import { configDir } from '../../license/index.js';
+const VAULT_SLOT = 'github_token';
+const GITHUB_API = 'https://api.github.com';
+/* ------------------ Tool specs ------------------ */
+export const CREATE_GITHUB_REPO_SPEC = {
+    name: 'forge.create_github_repo',
+    description: 'Create a new repository under the authenticated GitHub user. Requires vault slot github_token with repo scope. Returns the new repository metadata including clone_url.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Repository name (lowercase letters, digits, hyphens, underscores).' },
+            private: { type: 'boolean', description: 'Whether the new repository is private. Default true.' },
+            description: { type: 'string', description: 'Optional repository description.' },
+        },
+        required: ['name'],
+    },
+    requires_approval: true,
+};
+export const CLONE_REPO_SPEC = {
+    name: 'forge.clone_repo',
+    description: 'Clone a remote git repository to a local directory. Public repos need no auth. Private repos use the github_token slot when present. Returns the resolved target_dir + the first commit hash.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: 'Clone URL (https). Example: https://github.com/owner/repo.git' },
+            target_dir: { type: 'string', description: 'Where to clone (relative to projectRoot or absolute). Defaults to ./<repo-basename>.' },
+        },
+        required: ['url'],
+    },
+    requires_approval: true,
+};
+export const BRANCH_STATUS_SPEC = {
+    name: 'forge.branch_status',
+    description: 'Read the current git branch + dirty-tree status of a local checkout. Returns branch name, ahead/behind counters vs upstream when present, list of dirty files (max 50).',
+    input_schema: {
+        type: 'object',
+        properties: {
+            repo_dir: { type: 'string', description: 'Path to the git checkout. Relative to projectRoot or absolute. Default: projectRoot itself.' },
+        },
+        required: [],
+    },
+    requires_approval: false,
+};
+/* ------------------ Implementations ------------------ */
+const VALID_REPO_NAME = /^[a-zA-Z0-9._-]+$/;
+const MAX_DIRTY_FILES_REPORTED = 50;
+async function readToken(deps) {
+    const opener = deps.vaultOpener ?? (() => Vault.open({ configDir: configDir() }));
+    const vault = await opener();
+    if (!vault.has(VAULT_SLOT)) {
+        throw new Error('github: vault slot "' + VAULT_SLOT + '" not set. '
+            + 'Run `yf vault set ' + VAULT_SLOT + '` to configure your GitHub Personal Access Token (repo scope).');
+    }
+    return vault.get(VAULT_SLOT);
+}
+async function safeText(r) {
+    try {
+        return await r.text();
+    }
+    catch {
+        return '(no body)';
+    }
+}
+function defaultExec() {
+    return (cmd, args, opts) => new Promise((resolve, reject) => {
+        const proc = spawn(cmd, args, {
+            cwd: opts?.cwd,
+            env: opts?.env ?? process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (b) => { stdout += b.toString('utf-8'); });
+        proc.stderr.on('data', (b) => { stderr += b.toString('utf-8'); });
+        proc.on('error', reject);
+        proc.on('close', (code) => resolve({ code: code ?? 0, stdout, stderr }));
+    });
+}
+export async function runCreateGithubRepo(args, _ctx, deps = {}) {
+    if (typeof args.name !== 'string' || !VALID_REPO_NAME.test(args.name)) {
+        return {
+            tool: CREATE_GITHUB_REPO_SPEC.name,
+            result: { error: 'repo name must match [a-zA-Z0-9._-]+ (got: ' + JSON.stringify(args.name) + ')' },
+            is_error: true,
+            display: 'invalid name',
+        };
+    }
+    let token;
+    try {
+        token = await readToken(deps);
+    }
+    catch (err) {
+        return {
+            tool: CREATE_GITHUB_REPO_SPEC.name,
+            result: { error: err instanceof Error ? err.message : String(err) },
+            is_error: true,
+            display: 'vault read failed',
+        };
+    }
+    const fetchImpl = deps.fetchImpl ?? ((u, init) => globalThis.fetch(u, init));
+    const body = {
+        name: args.name,
+        private: args.private !== false, /* default true */
+        description: args.description ?? undefined,
+        auto_init: false,
+    };
+    const resp = await fetchImpl(GITHUB_API + '/user/repos', {
+        method: 'POST',
+        headers: {
+            Authorization: 'Bearer ' + token,
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+            'Content-Type': 'application/json',
+            'User-Agent': 'yujin-forge',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const detail = await safeText(resp);
+        return {
+            tool: CREATE_GITHUB_REPO_SPEC.name,
+            result: { error: 'GitHub API ' + resp.status + ': ' + detail.slice(0, 400) },
+            is_error: true,
+            display: 'create_repo failed',
+        };
+    }
+    const data = await resp.json();
+    return {
+        tool: CREATE_GITHUB_REPO_SPEC.name,
+        result: {
+            full_name: data.full_name,
+            html_url: data.html_url,
+            clone_url: data.clone_url,
+            ssh_url: data.ssh_url,
+            private: data.private,
+            default_branch: data.default_branch,
+        },
+        display: 'created ' + data.full_name,
+    };
+}
+export async function runCloneRepo(args, ctx, deps = {}) {
+    if (typeof args.url !== 'string' || args.url.trim() === '') {
+        return {
+            tool: CLONE_REPO_SPEC.name,
+            result: { error: 'url is required and must be a non-empty string' },
+            is_error: true,
+            display: 'missing url',
+        };
+    }
+    if (!/^https?:\/\//.test(args.url)) {
+        return {
+            tool: CLONE_REPO_SPEC.name,
+            result: { error: 'clone_repo only supports https URLs at the moment (got: ' + args.url + ')' },
+            is_error: true,
+            display: 'unsupported scheme',
+        };
+    }
+    const basename = path.basename(args.url).replace(/\.git$/, '');
+    if (basename === '') {
+        return {
+            tool: CLONE_REPO_SPEC.name,
+            result: { error: 'could not derive a target directory name from the URL: ' + args.url },
+            is_error: true,
+            display: 'bad url',
+        };
+    }
+    const rawTarget = args.target_dir ?? basename;
+    const target = path.isAbsolute(rawTarget) ? rawTarget : path.join(ctx.projectRoot, rawTarget);
+    /* Try to use the token when available. Public repos clone
+       without it; private repos fail clearly with stderr from
+       git itself if no token is set. */
+    let urlWithToken = args.url;
+    try {
+        const token = await readToken(deps);
+        /* Insert as user:token@host in the URL. Token survives
+           only in the argv of the spawned process for the brief
+           window of the clone. */
+        urlWithToken = args.url.replace(/^https?:\/\//, (m) => m + 'x-access-token:' + token + '@');
+    }
+    catch {
+        /* No token -- continue with the bare URL. Public repos work. */
+    }
+    const exec = deps.execImpl ?? defaultExec();
+    /* Make sure parent dir exists; git refuses to create nested
+       paths. */
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    const r = await exec('git', ['clone', urlWithToken, target]);
+    if (r.code !== 0) {
+        /* Strip the token from any echoed URL before surfacing. */
+        const safeErr = r.stderr.replace(/x-access-token:[^@]+@/g, 'x-access-token:[redacted]@');
+        return {
+            tool: CLONE_REPO_SPEC.name,
+            result: { error: 'git clone failed (exit ' + r.code + '): ' + safeErr.slice(0, 500).trim() },
+            is_error: true,
+            display: 'clone failed',
+        };
+    }
+    /* Get the first commit hash for the audit trail. */
+    let firstCommit = '';
+    const log = await exec('git', ['rev-parse', 'HEAD'], { cwd: target });
+    if (log.code === 0)
+        firstCommit = log.stdout.trim();
+    return {
+        tool: CLONE_REPO_SPEC.name,
+        result: {
+            target_dir: target,
+            head_commit: firstCommit,
+        },
+        display: 'cloned to ' + target,
+    };
+}
+export async function runBranchStatus(args, ctx, deps = {}) {
+    const repoDir = args.repo_dir
+        ? (path.isAbsolute(args.repo_dir) ? args.repo_dir : path.join(ctx.projectRoot, args.repo_dir))
+        : ctx.projectRoot;
+    const exec = deps.execImpl ?? defaultExec();
+    /* Verify the directory exists + is a git repo. */
+    const statRes = await fs.stat(repoDir).catch(() => null);
+    if (!statRes || !statRes.isDirectory()) {
+        return {
+            tool: BRANCH_STATUS_SPEC.name,
+            result: { error: 'repo_dir does not exist or is not a directory: ' + repoDir },
+            is_error: true,
+            display: 'bad repo_dir',
+        };
+    }
+    const branchRun = await exec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoDir });
+    if (branchRun.code !== 0) {
+        return {
+            tool: BRANCH_STATUS_SPEC.name,
+            result: { error: 'not a git checkout: ' + repoDir + ' (' + branchRun.stderr.trim().slice(0, 200) + ')' },
+            is_error: true,
+            display: 'not a git repo',
+        };
+    }
+    const branch = branchRun.stdout.trim();
+    /* Dirty file list via porcelain status. */
+    const statusRun = await exec('git', ['status', '--porcelain'], { cwd: repoDir });
+    const dirty = [];
+    if (statusRun.code === 0) {
+        for (const line of statusRun.stdout.split('\n')) {
+            const trimmed = line.replace(/^...\s*/, '').trim();
+            if (trimmed)
+                dirty.push(trimmed);
+            if (dirty.length >= MAX_DIRTY_FILES_REPORTED)
+                break;
+        }
+    }
+    /* Ahead / behind vs upstream (when upstream is configured). */
+    let ahead = 0;
+    let behind = 0;
+    let upstream = null;
+    const upstreamRun = await exec('git', ['rev-parse', '--abbrev-ref', '@{u}'], { cwd: repoDir });
+    if (upstreamRun.code === 0) {
+        upstream = upstreamRun.stdout.trim();
+        const counts = await exec('git', ['rev-list', '--left-right', '--count', branch + '...@{u}'], { cwd: repoDir });
+        if (counts.code === 0) {
+            const parts = counts.stdout.trim().split(/\s+/);
+            ahead = parseInt(parts[0] || '0', 10) || 0;
+            behind = parseInt(parts[1] || '0', 10) || 0;
+        }
+    }
+    return {
+        tool: BRANCH_STATUS_SPEC.name,
+        result: {
+            repo_dir: repoDir,
+            branch,
+            upstream,
+            ahead,
+            behind,
+            dirty_files: dirty,
+            dirty_truncated: statusRun.stdout.split('\n').filter((l) => l.trim()).length > MAX_DIRTY_FILES_REPORTED,
+        },
+        display: 'branch ' + branch
+            + (upstream ? ' (' + ahead + ' ahead, ' + behind + ' behind ' + upstream + ')' : ' (no upstream)')
+            + ', ' + dirty.length + ' dirty file(s)',
+    };
+}
+/* Exported for tests + registry wiring. */
+export { VAULT_SLOT };
+//# sourceMappingURL=github.js.map

package/dist/chat/tools/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../../../src/chat/tools/github.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,MAAM,UAAU,GAAG,cAAc,CAAC;AAClC,MAAM,UAAU,GAAG,wBAAwB,CAAC;AAe5C,sDAAsD;AAEtD,MAAM,CAAC,MAAM,uBAAuB,GAAa;IAC/C,IAAI,EAAE,0BAA0B;IAChC,WAAW,EAAE,yKAAyK;IACtL,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,oEAAoE,EAAE;YAC3G,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,sDAAsD,EAAE;YACjG,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kCAAkC,EAAE;SACjF;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;KACnB;IACD,iBAAiB,EAAE,IAAI;CACxB,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAa;IACvC,IAAI,EAAE,kBAAkB;IACxB,WAAW,EAAE,+LAA+L;IAC5M,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+DAA+D,EAAE;YACrG,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sFAAsF,EAAE;SACpI;QACD,QAAQ,EAAE,CAAC,KAAK,CAAC;KAClB;IACD,iBAAiB,EAAE,IAAI;CACxB,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAa;IAC1C,IAAI,EAAE,qBAAqB;IAC3B,WAAW,EAAE,yKAAyK;IACtL,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6FAA6F,EAAE;SACzI;QACD,QAAQ,EAAE,EAAE;KACb;IACD,iBAAiB,EAAE,KAAK;CACzB,CAAC;AAEF,2DAA2D;AAE3D,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAC5C,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAEpC,KAAK,UAAU,SAAS,CAAC,IAAgB;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IAClF,MAAM,KAAK,GAAG,MAAM,MAAM,EAAE,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,sBAAsB,GAAG,UAAU,GAAG,aAAa;cACjD,oBAAoB,GAAG,UAAU,GAAG,gEAAgE,CACvG,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAC/B,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,CAAW;IACjC,IAAI,CAAC;QAAC,OAAO,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,WAAW,CAAC;IAAC,CAAC;AAC9D,CAAC;AAED,SAAS,WAAW;IAClB,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE;YAC5B,GAAG,EAAE,IAAI,EAAE,GAAG;YACd,GAAG,EAAE,IAAI,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG;YAC7B,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;QACH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,MAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnE,IAAI,CAAC,MAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACzB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAA+D,EAC/D,IAAiB,EACjB,OAAmB,EAAE;IAErB,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO;YACL,IAAI,EAAE,uBAAuB,CAAC,IAAI;YAClC,MAAM,EAAE,EAAE,KAAK,EAAE,6CAA6C,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE;YAClG,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,cAAc;SACxB,CAAC;IACJ,CAAC;IACD,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QAAC,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IAAC,CAAC;IACtC,OAAO,GAAG,EAAE,CAAC;QACX,OAAO;YACL,IAAI,EAAE,uBAAuB,CAAC,IAAI;YAClC,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;YACnE,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,mBAAmB;SAC7B,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG;QACX,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO,KAAK,KAAK,EAAE,kBAAkB;QACnD,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,SAAS;QAC1C,SAAS,EAAE,KAAK;KACjB,CAAC;IACF,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,UAAU,GAAG,aAAa,EAAE;QACvD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,aAAa,EAAE,SAAS,GAAG,KAAK;YAChC,MAAM,EAAS,6BAA6B;YAC5C,sBAAsB,EAAE,YAAY;YACpC,cAAc,EAAE,kBAAkB;YAClC,YAAY,EAAG,aAAa;SAC7B;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO;YACL,IAAI,EAAE,uBAAuB,CAAC,IAAI;YAClC,MAAM,EAAE,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;YAC5E,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,oBAAoB;SAC9B,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAQ,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpC,OAAO;QACL,IAAI,EAAE,uBAAuB,CAAC,IAAI;QAClC,MAAM,EAAE;YACN,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,QAAQ,EAAG,IAAI,CAAC,QAAQ;YACxB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO,EAAI,IAAI,CAAC,OAAO;YACvB,OAAO,EAAI,IAAI,CAAC,OAAO;YACvB,cAAc,EAAE,IAAI,CAAC,cAAc;SACpC;QACD,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC,SAAS;KACrC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAA0C,EAC1C,GAAgB,EAChB,OAAmB,EAAE;IAErB,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3D,OAAO;YACL,IAAI,EAAE,eAAe,CAAC,IAAI;YAC1B,MAAM,EAAE,EAAE,KAAK,EAAE,gDAAgD,EAAE;YACnE,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,aAAa;SACvB,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,OAAO;YACL,IAAI,EAAE,eAAe,CAAC,IAAI;YAC1B,MAAM,EAAE,EAAE,KAAK,EAAE,0DAA0D,GAAG,IAAI,CAAC,GAAG,GAAG,GAAG,EAAE;YAC9F,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,oBAAoB;SAC9B,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC/D,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO;YACL,IAAI,EAAE,eAAe,CAAC,IAAI;YAC1B,MAAM,EAAE,EAAE,KAAK,EAAE,yDAAyD,GAAG,IAAI,CAAC,GAAG,EAAE;YACvF,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,SAAS;SACnB,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,IAAI,QAAQ,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAE9F;;wCAEoC;IACpC,IAAI,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;QACpC;;kCAE0B;QAC1B,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,iBAAiB,GAAG,KAAK,GAAG,GAAG,CAAC,CAAC;IAC9F,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC;IAC5C;gBACY;IACZ,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACjB,2DAA2D;QAC3D,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,wBAAwB,EAAE,4BAA4B,CAAC,CAAC;QACzF,OAAO;YACL,IAAI,EAAE,eAAe,CAAC,IAAI;YAC1B,MAAM,EAAE,EAAE,KAAK,EAAE,yBAAyB,GAAG,CAAC,CAAC,IAAI,GAAG,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YAC5F,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,cAAc;SACxB,CAAC;IACJ,CAAC;IACD,oDAAoD;IACpD,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;IACtE,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;QAAE,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACpD,OAAO;QACL,IAAI,EAAE,eAAe,CAAC,IAAI;QAC1B,MAAM,EAAE;YACN,UAAU,EAAE,MAAM;YAClB,WAAW,EAAE,WAAW;SACzB;QACD,OAAO,EAAE,YAAY,GAAG,MAAM;KAC/B,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAA2B,EAC3B,GAAgB,EAChB,OAAmB,EAAE;IAErB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ;QAC3B,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9F,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC;IAEpB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC;IAE5C,kDAAkD;IAClD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;QACvC,OAAO;YACL,IAAI,EAAE,kBAAkB,CAAC,IAAI;YAC7B,MAAM,EAAE,EAAE,KAAK,EAAE,iDAAiD,GAAG,OAAO,EAAE;YAC9E,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,cAAc;SACxB,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7F,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,kBAAkB,CAAC,IAAI;YAC7B,MAAM,EAAE,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE;YACxG,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,gBAAgB;SAC1B,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAEvC,2CAA2C;IAC3C,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IACjF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YACnD,IAAI,OAAO;gBAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACjC,IAAI,KAAK,CAAC,MAAM,IAAI,wBAAwB;gBAAE,MAAM;QACtD,CAAC;IACH,CAAC;IAED,+DAA+D;IAC/D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/F,IAAI,WAAW,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC3B,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QAChH,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAChD,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;YAC3C,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,kBAAkB,CAAC,IAAI;QAC7B,MAAM,EAAE;YACN,QAAQ,EAAE,OAAO;YACjB,MAAM;YACN,QAAQ;YACR,KAAK;YACL,MAAM;YACN,WAAW,EAAE,KAAK;YAClB,eAAe,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,wBAAwB;SACxG;QACD,OAAO,EAAE,SAAS,GAAG,MAAM;cACvB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC;cAChG,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,gBAAgB;KAC3C,CAAC;AACJ,CAAC;AAED,2CAA2C;AAC3C,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/chat/tools/lifecycle.d.ts

@@ -0,0 +1,82 @@
+/**
+ * App lifecycle tools (V1.13 of HITO 1).
+ *
+ * Three tools:
+ *   - forge.run_app(repo_dir?, command?, wait_for_url_ms?)
+ *   - forge.stop_app(pid?)
+ *   - forge.restart_app(repo_dir?, command?)
+ *
+ * Single-process model: at most one app runs per chat session.
+ * Multi-app concurrency is a v0.4+ slice.
+ *
+ * Spawn detection (when no explicit command is given):
+ *   1. Read package.json scripts.
+ *   2. Prefer `dev`, then `start`, then `serve`. Refuse loudly
+ *      when none exist.
+ *   3. Run via the matching package manager
+ *      (pnpm-lock.yaml -> pnpm, yarn.lock -> yarn, default
+ *      npm).
+ *
+ * URL detection is best-effort: monitor stdout for up to
+ * wait_for_url_ms (default 5000) looking for the typical
+ * "http://localhost:<port>" pattern. When found, return it;
+ * else return null with a note in the result.
+ *
+ * Loud failures per ROADMAP sec 12.2.
+ *
+ * ASCII-only.
+ */
+import type { ToolContext, ToolResult, ToolSpec } from '../tools.js';
+export interface RunningApp {
+    pid: number;
+    repo_dir: string;
+    command: string[];
+    started_at: string;
+    url: string | null;
+    /** Recent stdout / stderr buffer captured during URL detection
+     *  + the first few seconds after spawn. Useful in failure
+     *  reports. Bounded to ~16KB. */
+    recent_logs: string;
+}
+export interface LifecycleDeps {
+    /** Injects a fake child_process for tests. Returns the
+     *  process + the chosen command tuple. */
+    spawner?: (cmd: string, args: string[], cwd: string) => SpawnedProcess;
+    /** Filesystem layer for reading package.json + lockfiles
+     *  (also injectable for tests that don't want to write to
+     *  disk). */
+    readFile?: (p: string) => Promise<string>;
+    fileExists?: (p: string) => Promise<boolean>;
+}
+/** Subset of ChildProcess we actually use. Lets tests pass a
+ *  duck-typed object. */
+export interface SpawnedProcess {
+    pid: number | undefined;
+    stdout: {
+        on: (event: 'data', cb: (chunk: any) => void) => void;
+    } | null;
+    stderr: {
+        on: (event: 'data', cb: (chunk: any) => void) => void;
+    } | null;
+    on: (event: 'close' | 'error', cb: (...args: any[]) => void) => void;
+    kill: (signal?: string) => boolean;
+}
+export declare const RUN_APP_SPEC: ToolSpec;
+export declare const STOP_APP_SPEC: ToolSpec;
+export declare const RESTART_APP_SPEC: ToolSpec;
+export declare function runApp(args: {
+    repo_dir?: string;
+    command?: string;
+    wait_for_url_ms?: number;
+}, ctx: ToolContext, deps?: LifecycleDeps): Promise<ToolResult>;
+export declare function stopApp(args: {
+    pid?: number;
+}, _ctx: ToolContext, _deps?: LifecycleDeps): Promise<ToolResult>;
+export declare function restartApp(args: {
+    repo_dir?: string;
+    command?: string;
+    wait_for_url_ms?: number;
+}, ctx: ToolContext, deps?: LifecycleDeps): Promise<ToolResult>;
+/** Test seam: reset the singleton between test cases. */
+export declare function _resetLifecycleForTests(): void;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/chat/tools/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/chat/tools/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAKrE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB;;qCAEiC;IACjC,WAAW,EAAE,MAAM,CAAC;CACrB;AAUD,MAAM,WAAW,aAAa;IAC5B;8CAC0C;IAC1C,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,cAAc,CAAC;IACvE;;iBAEa;IACb,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C;AAED;yBACyB;AACzB,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,MAAM,EAAE;QAAE,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,KAAK,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACzE,MAAM,EAAE;QAAE,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,KAAK,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACzE,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,IAAI,CAAC;IACrE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACpC;AAMD,eAAO,MAAM,YAAY,EAAE,QAa1B,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,QAW3B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,QAa9B,CAAC;AAyDF,wBAAsB,MAAM,CAC1B,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,EACvE,GAAG,EAAE,WAAW,EAChB,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,UAAU,CAAC,CAiGrB;AAED,wBAAsB,OAAO,CAC3B,IAAI,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACtB,IAAI,EAAE,WAAW,EACjB,KAAK,GAAE,aAAkB,GACxB,OAAO,CAAC,UAAU,CAAC,CA0CrB;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,EACvE,GAAG,EAAE,WAAW,EAChB,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,UAAU,CAAC,CAkBrB;AAED,yDAAyD;AACzD,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}