@stacknext/cli 0.8.0 → 0.10.0

package/dist/agents.d.ts

@@ -0,0 +1,27 @@
+export declare const AGENTS_FILE_NAME = "AGENTS.md";
+export declare const AGENT_RULES_BEGIN = "<!-- BEGIN STACKNEXT AGENT RULES -->";
+export declare const AGENT_RULES_END = "<!-- END STACKNEXT AGENT RULES -->";
+export interface AgentPackageDocs {
+    name: string;
+    version: string;
+    docsPath: string;
+    visibility: 'public' | 'internal';
+    role: string;
+}
+export interface AgentRulesOptions {
+    version: string;
+    packages: AgentPackageDocs[];
+}
+export interface AgentRulesInstallResult {
+    file: string;
+    status: 'created' | 'appended' | 'updated' | 'unchanged';
+    changed: boolean;
+}
+export declare function discoverAgentPackages(projectDir: string): Promise<AgentPackageDocs[]>;
+export declare function renderAgentRules(options: AgentRulesOptions): string;
+/**
+ * Adds or replaces only the managed StackNext block. User content outside the
+ * markers is preserved exactly, including its line endings.
+ */
+export declare function installAgentRules(projectDir: string, options: AgentRulesOptions): Promise<AgentRulesInstallResult>;
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB,cAAc,CAAA;AAC3C,eAAO,MAAM,iBAAiB,yCAAyC,CAAA;AACvE,eAAO,MAAM,eAAe,uCAAuC,CAAA;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,QAAQ,GAAG,UAAU,CAAA;IACjC,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAA;IACxD,OAAO,EAAE,OAAO,CAAA;CACjB;AA6FD,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAgC7B;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAuDnE;AAkBD;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CAwDlC"}

package/dist/agents.js

@@ -0,0 +1,226 @@
+import { access, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export const AGENTS_FILE_NAME = 'AGENTS.md';
+export const AGENT_RULES_BEGIN = '<!-- BEGIN STACKNEXT AGENT RULES -->';
+export const AGENT_RULES_END = '<!-- END STACKNEXT AGENT RULES -->';
+const PACKAGE_DOCS = [
+    {
+        slug: 'cli',
+        name: '@stacknext/cli',
+        visibility: 'public',
+        role: 'CLI, collector and dashboard',
+    },
+    {
+        slug: 'next',
+        name: '@stacknext/next',
+        visibility: 'public',
+        role: 'Next.js instrumentation',
+    },
+    {
+        slug: 'core',
+        name: '@stacknext/core',
+        visibility: 'internal',
+        role: 'shared schemas, redaction and transport',
+    },
+    {
+        slug: 'diagnostics',
+        name: '@stacknext/diagnostics',
+        visibility: 'internal',
+        role: 'deterministic findings',
+    },
+    {
+        slug: 'regression',
+        name: '@stacknext/regression',
+        visibility: 'internal',
+        role: 'capture and comparison data',
+    },
+    {
+        slug: 'playwright',
+        name: '@stacknext/playwright',
+        visibility: 'public',
+        role: 'optional Playwright fixture',
+    },
+    {
+        slug: 'drizzle',
+        name: '@stacknext/drizzle',
+        visibility: 'public',
+        role: 'optional Drizzle adapter',
+    },
+    {
+        slug: 'prisma',
+        name: '@stacknext/prisma',
+        visibility: 'public',
+        role: 'optional Prisma adapter',
+    },
+    {
+        slug: 'mcp',
+        name: '@stacknext/mcp',
+        visibility: 'internal',
+        role: 'read-only MCP server',
+    },
+    {
+        slug: 'dashboard',
+        name: '@stacknext/dashboard',
+        visibility: 'internal',
+        role: 'static dashboard',
+    },
+];
+async function exists(file) {
+    try {
+        await access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findPackageDir(projectDir, slug) {
+    let current = path.resolve(projectDir);
+    for (;;) {
+        const candidate = path.join(current, 'node_modules', '@stacknext', slug);
+        if (await exists(path.join(candidate, 'package.json')))
+            return candidate;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export async function discoverAgentPackages(projectDir) {
+    const found = [];
+    const root = path.resolve(projectDir);
+    for (const entry of PACKAGE_DOCS) {
+        const packageDir = await findPackageDir(root, entry.slug);
+        if (!packageDir)
+            continue;
+        const manifestFile = path.join(packageDir, 'package.json');
+        const docsFile = path.join(packageDir, 'docs', 'index.md');
+        if (!(await exists(docsFile)))
+            continue;
+        try {
+            const manifest = JSON.parse(await readFile(manifestFile, 'utf8'));
+            const name = typeof manifest.name === 'string' ? manifest.name : entry.name;
+            const version = typeof manifest.version === 'string' ? manifest.version : 'unknown';
+            const docsPath = path
+                .relative(root, docsFile)
+                .split(path.sep)
+                .join('/');
+            found.push({
+                name,
+                version,
+                docsPath,
+                visibility: entry.visibility,
+                role: entry.role,
+            });
+        }
+        catch {
+            // An unreadable package manifest is not a reason to reference its docs.
+        }
+    }
+    return found;
+}
+export function renderAgentRules(options) {
+    const lines = [
+        AGENT_RULES_BEGIN,
+        '# StackNext',
+        '',
+        `StackNext is installed in this project (CLI v${options.version}). Its`,
+        'version-matched documentation ships inside each installed npm package.',
+        '',
+        'Before using or changing a StackNext API:',
+        '',
+    ];
+    const steps = [];
+    if (options.packages.length === 0) {
+        steps.push([
+            'No StackNext package docs were found under `node_modules`. Install',
+            '`@stacknext/cli` and the packages you use, then re-run',
+            '`stacknext init --agents`. Do not assume package APIs are available.',
+        ].join('\n'));
+    }
+    else {
+        const cli = options.packages.find((entry) => entry.name === '@stacknext/cli');
+        if (cli) {
+            steps.push(`Read \`${cli.docsPath}\` for the local documentation entry point.`);
+        }
+        const installed = options.packages
+            .map((entry) => `- \`${entry.docsPath}\` — ${entry.name} ${entry.version} (${entry.visibility}, ${entry.role})`)
+            .join('\n');
+        steps.push(`Read the package docs for every StackNext package involved in the task:\n${installed}`);
+        steps.push('Confirm the installed version in the package.json next to each\ndocumentation directory. Do not apply documentation for another version.');
+    }
+    steps.push('Prefer the local documentation over external docs or model memory.', 'Do not assume undocumented exports, configuration keys, internal\npackages or integrations exist.', 'For runtime investigation, use the StackNext MCP tools where available.\nStart with `get_project_summary`; the server is local and read-only.', 'Follow the installed `stacknext-debugging` Agent Skill for debugging and\nperformance workflows.', 'Treat diagnostic findings as evidence, not confirmed root causes, and\n`inconclusive` regression comparisons as inconclusive, not passes.', 'Verify changes against the installed implementation and tests where\navailable. Do not invent a fallback API when a package is absent.');
+    for (const [index, step] of steps.entries()) {
+        const [first, ...rest] = step.split('\n');
+        lines.push(`${index + 1}. ${first}`, ...rest.map((line) => `   ${line}`));
+    }
+    lines.push(AGENT_RULES_END);
+    return lines.join('\n');
+}
+function count(haystack, needle) {
+    return haystack.split(needle).length - 1;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function detectNewline(source) {
+    return source.includes('\r\n') ? '\r\n' : '\n';
+}
+function withNewline(block, newline) {
+    return newline === '\n' ? block : block.replace(/\n/g, newline);
+}
+/**
+ * Adds or replaces only the managed StackNext block. User content outside the
+ * markers is preserved exactly, including its line endings.
+ */
+export async function installAgentRules(projectDir, options) {
+    const file = path.join(projectDir, AGENTS_FILE_NAME);
+    const block = renderAgentRules(options);
+    let source;
+    let created = false;
+    try {
+        source = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        source = '';
+        created = true;
+    }
+    const begins = count(source, AGENT_RULES_BEGIN);
+    const ends = count(source, AGENT_RULES_END);
+    if (begins > 1 || ends > 1) {
+        throw new Error(`${file} contains more than one StackNext managed block. Remove the duplicates before running init again.`);
+    }
+    if (begins !== ends) {
+        throw new Error(`${file} contains an incomplete StackNext managed block. Restore or remove the missing marker before running init again.`);
+    }
+    const newline = detectNewline(source);
+    let next;
+    let status;
+    if (begins === 1 && ends === 1) {
+        const pattern = new RegExp(`${escapeRegExp(AGENT_RULES_BEGIN)}[\\s\\S]*?${escapeRegExp(AGENT_RULES_END)}`);
+        if (!pattern.test(source)) {
+            throw new Error(`${file} has StackNext markers in an unexpected order. Fix them manually before running init again.`);
+        }
+        next = source.replace(pattern, withNewline(block, newline));
+        status = next === source ? 'unchanged' : 'updated';
+    }
+    else if (created || source.trim() === '') {
+        next = `${withNewline(block, newline)}${newline}`;
+        status = 'created';
+    }
+    else {
+        const separator = source.endsWith(`${newline}${newline}`)
+            ? ''
+            : source.endsWith(newline)
+                ? newline
+                : `${newline}${newline}`;
+        next = `${source}${separator}${withNewline(block, newline)}${newline}`;
+        status = 'appended';
+    }
+    if (next !== source)
+        await writeFile(file, next);
+    return { file, status, changed: next !== source };
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}

package/dist/commands/init.d.ts

@@ -5,6 +5,8 @@ export declare function manualPatchSnippet(): string;
 export declare function fileExists(file: string): Promise<boolean>;
 export interface InitOptions {
     install?: boolean;
+    agents?: boolean;
+    skipAgents?: boolean;
 }
 export declare function runInit(options: InitOptions, cwd?: string): Promise<number>;
 export declare function registerInitCommand(program: Command, cwd: string): void;

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqBxC,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,CA+CpE;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAMlE;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAU3C;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAoBD,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,SAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HxF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CASvE"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAuBxC,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,CA+CpE;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAMlE;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAU3C;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAoBD,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,SAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiJxF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAWvE"}

package/dist/commands/init.js

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { CONFIG_FILE_NAME, configPath, loadConfig } from '@stacknext/core/config-file';
 import { detectProject, installCommand, isStackNextIntegrated, } from '../project.js';
 import { printCheck, printSection, style } from '../output.js';
+import { CLI_VERSION } from '../version.js';
+import { discoverAgentPackages, installAgentRules } from '../agents.js';
 function instrumentationTarget(project) {
     const inSrc = project.appDir?.startsWith('src/') === true ||
         (project.appDir === null && project.srcDir);
@@ -183,6 +185,24 @@ export async function runInit(options, cwd = process.cwd()) {
     if (project.hasPrisma) {
         printCheck('warn', 'Prisma detected', 'Add instrumentPrismaClient() from @stacknext/prisma after creating PrismaClient.');
     }
+    if (options.agents && !options.skipAgents) {
+        const packages = await discoverAgentPackages(project.dir);
+        const installed = await installAgentRules(project.dir, {
+            version: CLI_VERSION,
+            packages,
+        });
+        if (installed.status === 'unchanged') {
+            printCheck('pass', `${installed.file} is up to date`, 'managed StackNext block');
+        }
+        else {
+            const action = installed.status === 'created'
+                ? 'Created'
+                : installed.status === 'appended'
+                    ? 'Appended StackNext rules to'
+                    : 'Updated StackNext rules in';
+            printCheck('pass', `${action} ${path.relative(project.dir, installed.file)}`, 'managed block only');
+        }
+    }
     printSection('Next steps');
     console.log(`1. Run ${style.cyan('stacknext dev')} (or ${style.cyan('stacknext dev --install')} if packages are missing).`);
     console.log(`2. Open the dashboard and make a request to your app.`);
@@ -195,6 +215,8 @@ export function registerInitCommand(program, cwd) {
         .command('init')
         .description('Configure a Next.js project for StackNext')
         .option('--install', 'install @stacknext/next with the detected package manager')
+        .option('--agents', 'add or update the managed StackNext block in AGENTS.md')
+        .option('--skip-agents', 'skip the AGENTS.md managed block (the default)')
         .action(async (options) => {
         const code = await runInit(options, cwd);
         if (code !== 0)

package/dist/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.8.0";
+export declare const CLI_VERSION = "0.10.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,UAAU,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,WAAW,CAAA"}

package/dist/version.js

@@ -1,2 +1,2 @@
-export const CLI_VERSION = '0.8.0';
+export const CLI_VERSION = '0.10.0';
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAA"}

package/docs/agent-setup.md

@@ -0,0 +1,120 @@
+---
+title: Agent setup
+description: Install StackNext agent instructions, the Agent Skill and the MCP server.
+---
+
+# Agent setup
+
+StackNext has three complementary agent surfaces. They do not replace one
+another.
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:6cb91359416b90497c8a30b4e48bca6633004719cf0d0075494ac3fd6e33f50a -->
+
+| Surface | Purpose | Command |
+| --- | --- | --- |
+| Local package documentation | Version-matched API reference | Ships in the seven documented packages |
+| Managed `AGENTS.md` block | Short project rules and documentation pointers | `stacknext init --agents` |
+| Agent Skill | Detailed evidence-first workflows | `stacknext skill install` |
+| MCP server | Read-only runtime evidence | `stacknext mcp` |
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## 1. Local documentation
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:5322f074c4bd22377289b52567028ebfbba0bcf2a8678742f28a42cbc3ec8e3c -->
+
+The seven packages listed in `DOCUMENTED_PACKAGES` ship `docs/`:
+`@stacknext/cli`, `@stacknext/next`, `@stacknext/core`,
+`@stacknext/regression`, `@stacknext/playwright`, `@stacknext/drizzle` and
+`@stacknext/prisma`. Start with the CLI package's
+`docs/index.md`; the managed block below records its actual path, which may be
+at the workspace root. The generated [package index](packages.md) lists the
+documented packages and which docs to read.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+No command is needed; the docs are part of the package archive.
+
+## 2. Managed `AGENTS.md` block
+
+```bash
+stacknext init --agents
+```
+
+This adds a marked block to the project's `AGENTS.md`:
+
+```md
+<!-- BEGIN STACKNEXT AGENT RULES -->
+...
+<!-- END STACKNEXT AGENT RULES -->
+```
+
+Safety properties:
+
+- An existing `AGENTS.md` is never overwritten.
+- Content outside the markers is preserved byte-for-byte (line endings are
+  preserved).
+- Re-running updates only the block; it never duplicates it.
+- If only one marker exists, the file is left unchanged and the command fails
+  with a clear error instead of guessing.
+- If no `AGENTS.md` exists, one is created.
+- `--skip-agents` is an explicit opt-out for scripts. Agent setup is off by
+  default.
+
+The block points agents at available package docs and the current StackNext
+version. If no package docs are found, it says so instead of referencing
+nonexistent paths.
+
+## 3. Agent Skill
+
+```bash
+stacknext skill install --client opencode
+stacknext skill install --client codex
+stacknext skill install --client claude-code
+```
+
+| Client | Project path |
+| --- | --- |
+| OpenCode | `.opencode/skills/stacknext-debugging` |
+| Codex | `.agents/skills/stacknext-debugging` |
+| Claude Code | `.claude/skills/stacknext-debugging` |
+
+`stacknext skill path` prints the bundled directory and version. `--force`
+replaces an existing skill copy; without it, an existing destination is left
+untouched and the command exits 1.
+
+## 4. MCP server
+
+```bash
+stacknext dev     # collector must be running
+stacknext mcp     # stdio server
+```
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:95c82a21ffd412dd8a9b62c44104a3f93a3959e02214cd944fb055ce979258e0 -->
+
+Configure the client to start the command from the app directory. See
+[commands](commands.md) for `stacknext mcp` and
+[troubleshooting](troubleshooting.md) for client connection issues.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## Recommended order
+
+1. Install and initialize StackNext.
+2. Run `stacknext init --agents` if the project uses `AGENTS.md`.
+3. Install the skill for the client you use.
+4. Configure the MCP server.
+5. Start `stacknext dev` before the agent investigates.
+
+## What StackNext does not do
+
+- It does not modify `CLAUDE.md`, `.cursor/rules`, Copilot instructions or
+  global client configuration.
+- It does not install the skill without an explicit client flag.
+- It does not add MCP configuration automatically to arbitrary clients.