@webpresso/agent-kit 0.21.0

package/dist/esm/cli/commands/init/detect-consumer.js

@@ -0,0 +1,279 @@
+/**
+ * Detect the consumer repo that `wp init` is running against.
+ *
+ * Walks for a `.git` directory (the consumer is not required to use pnpm
+ * workspaces — single-package projects are fine). Reads `package.json` and
+ * `pnpm-workspace.yaml` when present to power downstream template rendering.
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readConfig } from './config.js';
+export function findGitRoot(startDir) {
+    let current = path.resolve(startDir);
+    for (;;) {
+        if (existsSync(path.join(current, '.git')))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export function readPackageJson(repoRoot) {
+    const candidate = path.join(repoRoot, 'package.json');
+    if (!existsSync(candidate))
+        return { path: null, info: null };
+    try {
+        const raw = readFileSync(candidate, 'utf8');
+        const parsed = JSON.parse(raw);
+        const name = typeof parsed['name'] === 'string' ? parsed['name'] : path.basename(repoRoot);
+        const version = typeof parsed['version'] === 'string' ? parsed['version'] : undefined;
+        const deps = (parsed['dependencies'] ?? {});
+        const devDeps = (parsed['devDependencies'] ?? {});
+        return {
+            path: candidate,
+            info: { name, version, dependencies: deps, devDependencies: devDeps },
+        };
+    }
+    catch {
+        return { path: candidate, info: null };
+    }
+}
+/**
+ * Parse `pnpm-workspace.yaml` enough to extract the `packages:` glob list.
+ * We avoid pulling in a YAML dep for this — the file format is stable and
+ * we only need the `packages:` block.
+ */
+export function parseWorkspaceGlobs(repoRoot) {
+    const wsPath = path.join(repoRoot, 'pnpm-workspace.yaml');
+    if (!existsSync(wsPath))
+        return null;
+    try {
+        const raw = readFileSync(wsPath, 'utf8');
+        const globs = [];
+        let inPackages = false;
+        for (const rawLine of raw.split('\n')) {
+            const line = rawLine.replace(/\r$/, '');
+            if (/^packages:\s*$/.test(line)) {
+                inPackages = true;
+                continue;
+            }
+            if (inPackages) {
+                const trimmed = line.trim();
+                // Stop at a new top-level key
+                if (line.length > 0 &&
+                    !line.startsWith(' ') &&
+                    !line.startsWith('-') &&
+                    !line.startsWith('\t')) {
+                    inPackages = false;
+                    continue;
+                }
+                const match = /^-\s*['"]?([^'"\s#]+)['"]?/.exec(trimmed);
+                if (match && match[1])
+                    globs.push(match[1]);
+            }
+        }
+        return globs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Expand a pnpm workspace glob against `repoRoot`, returning resolved
+ * package directories that contain a `package.json`.
+ *
+ * Supports: `pkg/foo`, `pkg/*`, `pkg/**`. Globs are applied at directory
+ * boundaries; we don't need full glob semantics.
+ */
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function safeRealpath(target) {
+    try {
+        return realpathSync(target);
+    }
+    catch {
+        return null;
+    }
+}
+function isWithinPath(target, root) {
+    const relative = path.relative(root, target);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function discoverInstalledWebpressoRoots(repoRoot) {
+    const roots = new Set();
+    const directRoot = path.join(repoRoot, 'node_modules', 'webpresso');
+    if (existsSync(path.join(directRoot, 'package.json'))) {
+        roots.add(directRoot);
+    }
+    const pnpmRoot = path.join(repoRoot, 'node_modules', '.pnpm');
+    for (const entry of safeReaddir(pnpmRoot)) {
+        if (!entry.startsWith('webpresso@'))
+            continue;
+        const candidate = path.join(pnpmRoot, entry, 'node_modules', 'webpresso');
+        if (existsSync(path.join(candidate, 'package.json'))) {
+            roots.add(candidate);
+        }
+    }
+    return [...roots];
+}
+function isLocalWebpressoCli(repoRoot, cliPath) {
+    const cliCandidates = [
+        ...new Set([cliPath, safeRealpath(cliPath)].filter((p) => p !== null)),
+    ];
+    if (cliCandidates.length === 0)
+        return false;
+    for (const root of discoverInstalledWebpressoRoots(repoRoot)) {
+        const rootCandidates = [
+            ...new Set([root, safeRealpath(root)].filter((p) => p !== null)),
+        ];
+        for (const candidate of cliCandidates) {
+            if (rootCandidates.some((rootPath) => isWithinPath(candidate, rootPath))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function isDirectory(full) {
+    try {
+        return statSync(full).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function expandGlob(repoRoot, glob) {
+    const segments = glob.split('/').filter((s) => s.length > 0);
+    let frontier = [repoRoot];
+    for (const segment of segments) {
+        const next = [];
+        for (const dir of frontier) {
+            if (!existsSync(dir))
+                continue;
+            if (segment === '**') {
+                const stack = [dir];
+                while (stack.length > 0) {
+                    const popped = stack.pop();
+                    if (popped === undefined)
+                        break;
+                    next.push(popped);
+                    for (const entry of safeReaddir(popped)) {
+                        if (entry === 'node_modules' || entry.startsWith('.'))
+                            continue;
+                        const full = path.join(popped, entry);
+                        if (isDirectory(full))
+                            stack.push(full);
+                    }
+                }
+            }
+            else if (segment === '*') {
+                for (const entry of safeReaddir(dir)) {
+                    if (entry === 'node_modules' || entry.startsWith('.'))
+                        continue;
+                    const full = path.join(dir, entry);
+                    if (isDirectory(full))
+                        next.push(full);
+                }
+            }
+            else {
+                const full = path.join(dir, segment);
+                if (isDirectory(full))
+                    next.push(full);
+            }
+        }
+        frontier = next;
+    }
+    return frontier;
+}
+export function discoverWorkspacePackages(repoRoot, globs) {
+    if (!globs || globs.length === 0)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const glob of globs) {
+        for (const dir of expandGlob(repoRoot, glob)) {
+            const pkgPath = path.join(dir, 'package.json');
+            if (seen.has(dir))
+                continue;
+            if (!existsSync(pkgPath))
+                continue;
+            seen.add(dir);
+            try {
+                const raw = readFileSync(pkgPath, 'utf8');
+                const parsed = JSON.parse(raw);
+                const fullName = typeof parsed.name === 'string' ? parsed.name : path.basename(dir);
+                const shortName = fullName.includes('/') ? (fullName.split('/')[1] ?? fullName) : fullName;
+                out.push({
+                    name: fullName,
+                    relativePath: path.relative(repoRoot, dir) || '.',
+                    absolutePath: dir,
+                    shortName,
+                });
+            }
+            catch {
+                /* skip malformed package */
+            }
+        }
+    }
+    return out.toSorted((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Soft warning when the running CLI does not resolve to the consumer's local
+ * `webpresso` install. Catches the global-install / pnpm-link / npx
+ * case where `wp setup` succeeds against the executing CLI's catalog but
+ * produces a non-reproducible `.agents/skills/` tree (symlinks point outside
+ * the project tree; lockfile irrelevant). Repo-local symlink/dev-link installs
+ * still count as local via realpath comparison. Self-mode short-circuits when
+ * the consumer IS `webpresso` (running setup from webpresso's own
+ * checkout).
+ *
+ * Non-blocking: prints to stderr and returns. The bc88-class failure
+ * (catalog truly missing) is caught by the catch-wrap in `runInit` via
+ * `loadContent`'s throw — this is the orthogonal silent-non-determinism
+ * class that the catch-wrap doesn't surface.
+ */
+export function warnIfNonLocalCli(repoRoot, cliUrl = import.meta.url) {
+    const ourPkg = readPackageJson(repoRoot).info;
+    if (ourPkg?.name === 'webpresso')
+        return;
+    if (readConfig(repoRoot)?.globalInstall === true)
+        return;
+    let cliPath;
+    try {
+        cliPath = fileURLToPath(cliUrl);
+    }
+    catch {
+        return;
+    }
+    if (isLocalWebpressoCli(repoRoot, cliPath))
+        return;
+    const hasLocalWebpressoDep = ourPkg?.dependencies['webpresso'] ?? ourPkg?.devDependencies['webpresso'];
+    console.error(`warning: wp running from a non-local install (${cliPath}). ` +
+        (hasLocalWebpressoDep
+            ? 'This repo already pins `webpresso`; rerun via the repo-local CLI (`vp run setup:agent` or `vp exec wp setup`).'
+            : 'Pin `webpresso` as a local dep for reproducible setup.'));
+}
+export function detectConsumer(startDir = process.cwd()) {
+    const repoRoot = findGitRoot(startDir);
+    if (!repoRoot)
+        return null;
+    const { path: pkgPath, info } = readPackageJson(repoRoot);
+    const globs = parseWorkspaceGlobs(repoRoot);
+    const workspacePackages = discoverWorkspacePackages(repoRoot, globs);
+    return {
+        repoRoot,
+        packageJsonPath: pkgPath,
+        packageJson: info,
+        hasPnpmWorkspace: globs !== null,
+        workspacePackages,
+    };
+}
+//# sourceMappingURL=detect-consumer.js.map

package/dist/esm/cli/commands/init/gitignore-patcher.d.ts

@@ -0,0 +1,9 @@
+import type { MergeOptions, MergeResult } from './merge.js';
+export interface GitignoreBlock {
+    id: string;
+    patterns: readonly string[];
+}
+/** Canonical gitignore block for webpresso generated/transient paths. */
+export declare const GENERATED_PATHS_BLOCK: GitignoreBlock;
+export declare function patchGitignore(targetPath: string, block: GitignoreBlock, opts?: MergeOptions): MergeResult;
+//# sourceMappingURL=gitignore-patcher.d.ts.map

package/dist/esm/cli/commands/init/gitignore-patcher.js

@@ -0,0 +1,133 @@
+/**
+ * Idempotent `.gitignore` patcher anchored by marker comments.
+ *
+ * Each managed block is wrapped between:
+ *   # >>> managed by webpresso (<id>)
+ *   <patterns>
+ *   # <<< managed by webpresso (<id>)
+ *
+ * Re-running the patcher detects an existing block by id and either leaves
+ * it alone (when content matches) or rewrites just that block (overwrite or
+ * drift). Other content in `.gitignore` — including unrelated managed blocks
+ * from other scaffolders — is preserved verbatim.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const BEGIN = (id) => `# >>> managed by webpresso (${id})`;
+const END = (id) => `# <<< managed by webpresso (${id})`;
+function renderBlock(block) {
+    return [BEGIN(block.id), ...block.patterns, END(block.id)].join('\n');
+}
+function findBlock(content, id) {
+    const begin = BEGIN(id);
+    const end = END(id);
+    const lines = content.split('\n');
+    let startLine = -1;
+    let endLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i] === begin && startLine === -1)
+            startLine = i;
+        else if (lines[i] === end && startLine !== -1) {
+            endLine = i;
+            break;
+        }
+    }
+    if (startLine === -1 || endLine === -1)
+        return null;
+    return { start: startLine, end: endLine };
+}
+/** Canonical gitignore block for webpresso generated/transient paths. */
+export const GENERATED_PATHS_BLOCK = {
+    id: 'generated',
+    patterns: [
+        '# Agent surfaces are regenerated by `wp setup` / `wp symlink sync` / `omx setup`.',
+        '# Commit canonical sources (`agent-skills/`, `agent-rules/`, catalog) instead.',
+        '# Ignore generated projections and local-only runtime state, but avoid',
+        '# blanket tool-root ignores when repos may deliberately commit specific',
+        '# instruction surfaces (for example selected `.claude/*` files).',
+        '.agent/',
+        '.agents/',
+        '.gemini/',
+        '.cursor/',
+        '.windsurf/',
+        '.omx/',
+        '.omc/',
+        '.opencode/',
+        '.codex/',
+        '.claude/settings.json',
+        '.claude/agents/',
+        '.claude/hooks/',
+        '.claude/rules/',
+        '.claude/skills/',
+        '.claude/worktrees/',
+        '.claude/scheduled_tasks.lock',
+        '.cursor/rules/',
+        '.windsurf/skills/',
+        '.windsurf/rules/',
+        '.gemini/commands/',
+        '.opencode/agents/',
+        '.opencode/commands/',
+        '.agents/skills/',
+        '.agent/.merged.provenance.json',
+        '.agent/.compile-manifest.json',
+        '.agent/.rotation-log.jsonl',
+        '.agent/.blueprints.db',
+        '.agent/.blueprints.lock',
+        '.agent/.blueprints.snapshot.sql',
+        '.agent/.tail-hint-history.jsonl',
+    ],
+};
+export function patchGitignore(targetPath, block, opts = {}) {
+    const exists = existsSync(targetPath);
+    const original = exists ? readFileSync(targetPath, 'utf8') : '';
+    const rendered = renderBlock(block);
+    let next;
+    let action;
+    const found = findBlock(original, block.id);
+    if (found) {
+        const lines = original.split('\n');
+        const currentBlock = lines.slice(found.start, found.end + 1).join('\n');
+        const trailingContent = lines.slice(found.end + 1).some((line) => line.trim().length > 0);
+        if (block.id === 'generated' && opts.overwrite && trailingContent) {
+            const withoutBlock = [...lines.slice(0, found.start), ...lines.slice(found.end + 1)]
+                .join('\n')
+                .replace(/\s+$/, '');
+            next = withoutBlock.length === 0 ? `${rendered}\n` : `${withoutBlock}\n\n${rendered}\n`;
+            action = 'overwritten';
+        }
+        else if (currentBlock === rendered) {
+            return { targetPath, action: 'identical' };
+        }
+        else {
+            if (!opts.overwrite) {
+                // Drift: existing block diverges from canonical content. Leave it alone
+                // (consumer-edited) and surface drift.
+                return { targetPath, action: 'drifted' };
+            }
+            const before = lines.slice(0, found.start);
+            const after = lines.slice(found.end + 1);
+            next = [...before, rendered, ...after].join('\n');
+            action = 'overwritten';
+        }
+    }
+    else {
+        if (original.length === 0) {
+            next = `${rendered}\n`;
+        }
+        else {
+            // Normalise trailing whitespace so re-adding a previously-deleted block
+            // produces byte-identical output to the original write — and so we never
+            // stack blank lines when the file already ends with one.
+            const trimmed = original.replace(/\s+$/, '');
+            next = trimmed.length === 0 ? `${rendered}\n` : `${trimmed}\n\n${rendered}\n`;
+        }
+        action = exists ? 'overwritten' : 'created';
+    }
+    if (opts.dryRun) {
+        return { targetPath, action: 'skipped-dry' };
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, next);
+    return { targetPath, action };
+}
+//# sourceMappingURL=gitignore-patcher.js.map

package/dist/esm/cli/commands/init/host-visibility.d.ts

@@ -0,0 +1,37 @@
+export declare const AGENT_HOSTS: readonly ["codex", "claude", "opencode"];
+export type AgentHost = (typeof AGENT_HOSTS)[number];
+export declare const REQUIRED_CORE_CAPABILITIES: readonly ["verify", "plan-refine"];
+export declare const VISIBILITY_STATUSES: readonly ["visible-now", "visible-after-restart", "not-visible"];
+export type VisibilityStatus = (typeof VISIBILITY_STATUSES)[number];
+export interface HostSkillRoots {
+    readonly project: readonly string[];
+    readonly user: readonly string[];
+    readonly global: readonly string[];
+}
+export interface HostSkillVisibility {
+    readonly host: AgentHost;
+    readonly capability: string;
+    readonly status: VisibilityStatus;
+    readonly checkedRoots: readonly string[];
+    readonly foundPaths: readonly string[];
+    readonly restartRequired: boolean;
+}
+export interface HostVisibilityAudit {
+    readonly selectedHosts: readonly AgentHost[];
+    readonly requiredCapabilities: readonly string[];
+    readonly results: readonly HostSkillVisibility[];
+}
+export interface AuditHostSkillVisibilityInput {
+    readonly repoRoot: string;
+    readonly hosts?: readonly AgentHost[];
+    readonly requiredCapabilities?: readonly string[];
+    readonly homeDir?: string;
+    /** Slugs already observed in the active host session. Omit when a restart is needed. */
+    readonly liveSkillSlugs?: ReadonlySet<string>;
+}
+export declare function parseAgentHosts(value: string | undefined): AgentHost[];
+export declare function hostSkillRoots(repoRoot: string, host: AgentHost, homeDir?: string): HostSkillRoots;
+export declare function auditHostSkillVisibility(input: AuditHostSkillVisibilityInput): HostVisibilityAudit;
+export declare function serializeHostVisibility(audit: HostVisibilityAudit): Record<string, Record<string, VisibilityStatus>>;
+export declare function summarizeHostVisibility(repoRoot: string, audit: HostVisibilityAudit): string[];
+//# sourceMappingURL=host-visibility.d.ts.map

package/dist/esm/cli/commands/init/host-visibility.js

@@ -0,0 +1,105 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, relative } from 'node:path';
+export const AGENT_HOSTS = ['codex', 'claude', 'opencode'];
+export const REQUIRED_CORE_CAPABILITIES = ['verify', 'plan-refine'];
+export const VISIBILITY_STATUSES = ['visible-now', 'visible-after-restart', 'not-visible'];
+export function parseAgentHosts(value) {
+    if (!value || value.trim().length === 0 || value.trim() === 'all')
+        return [...AGENT_HOSTS];
+    const out = [];
+    const unknown = [];
+    for (const raw of value.split(',')) {
+        const token = raw.trim();
+        if (!token)
+            continue;
+        if (AGENT_HOSTS.includes(token))
+            out.push(token);
+        else
+            unknown.push(token);
+    }
+    if (unknown.length > 0) {
+        throw new Error(`Unknown host(s): ${unknown.join(', ')}. Expected one of: ${AGENT_HOSTS.join(', ')}, all.`);
+    }
+    return [...new Set(out)];
+}
+export function hostSkillRoots(repoRoot, host, homeDir = homedir()) {
+    switch (host) {
+        case 'codex':
+            return {
+                project: [join(repoRoot, '.agents', 'skills')],
+                user: [join(homeDir, '.agents', 'skills')],
+                global: ['/etc/codex/skills'],
+            };
+        case 'claude':
+            return {
+                project: [join(repoRoot, '.claude', 'skills')],
+                user: [join(homeDir, '.claude', 'skills')],
+                global: [],
+            };
+        case 'opencode':
+            return {
+                project: [
+                    join(repoRoot, '.opencode', 'skills'),
+                    join(repoRoot, '.claude', 'skills'),
+                    join(repoRoot, '.agents', 'skills'),
+                ],
+                user: [
+                    join(homeDir, '.config', 'opencode', 'skills'),
+                    join(homeDir, '.claude', 'skills'),
+                    join(homeDir, '.agents', 'skills'),
+                ],
+                global: [],
+            };
+    }
+}
+export function auditHostSkillVisibility(input) {
+    const selectedHosts = input.hosts && input.hosts.length > 0 ? [...input.hosts] : [...AGENT_HOSTS];
+    const requiredCapabilities = input.requiredCapabilities && input.requiredCapabilities.length > 0
+        ? [...input.requiredCapabilities]
+        : [...REQUIRED_CORE_CAPABILITIES];
+    const results = [];
+    for (const host of selectedHosts) {
+        const roots = hostSkillRoots(input.repoRoot, host, input.homeDir);
+        const checkedRoots = [...roots.project, ...roots.user, ...roots.global];
+        for (const capability of requiredCapabilities) {
+            const foundPaths = checkedRoots
+                .map((root) => join(root, capability, 'SKILL.md'))
+                .filter((path) => existsSync(path));
+            const status = foundPaths.length === 0
+                ? 'not-visible'
+                : input.liveSkillSlugs?.has(capability) === true
+                    ? 'visible-now'
+                    : 'visible-after-restart';
+            results.push({
+                host,
+                capability,
+                status,
+                checkedRoots,
+                foundPaths,
+                restartRequired: status === 'visible-after-restart',
+            });
+        }
+    }
+    return { selectedHosts, requiredCapabilities, results };
+}
+export function serializeHostVisibility(audit) {
+    const byHost = {};
+    for (const result of audit.results) {
+        byHost[result.host] ??= {};
+        byHost[result.host][result.capability] = result.status;
+    }
+    return byHost;
+}
+export function summarizeHostVisibility(repoRoot, audit) {
+    return audit.results.map((result) => {
+        const detail = result.foundPaths.length > 0
+            ? result.foundPaths.map((path) => relative(repoRoot, path).replaceAll('\\', '/')).join(', ')
+            : result.checkedRoots
+                .map((path) => relative(repoRoot, path).replaceAll('\\', '/'))
+                .join(', ');
+        const marker = result.status === 'not-visible' ? '✗' : result.status === 'visible-now' ? '✓' : '↻';
+        return `  ${result.host}: ${marker} ${result.capability} ${result.status} (${detail})`;
+    });
+}
+//# sourceMappingURL=host-visibility.js.map

package/dist/esm/cli/commands/init/index.d.ts

@@ -0,0 +1,23 @@
+import type { CAC } from 'cac';
+export interface InitFlags {
+    with?: string;
+    without?: string;
+    host?: string;
+    all?: boolean;
+    overwrite?: boolean;
+    'dry-run'?: boolean;
+    dryRun?: boolean;
+    yes?: boolean;
+    cwd?: string;
+    strict?: boolean;
+    project?: boolean;
+}
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_SETUP_FAIL = 1;
+export declare const EXIT_USER_ABORT = 2;
+export declare const EXIT_WRITE_FAIL = 3;
+export declare function resolveCatalogDir(): string;
+export declare function runInit(flags: InitFlags): Promise<number>;
+export type InitCommandName = 'setup' | 'init';
+export declare function registerInitCommand(cli: CAC, commandName?: InitCommandName): void;
+//# sourceMappingURL=index.d.ts.map