@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/smiths/context-pipeline/claude-hook.js

@@ -0,0 +1,127 @@
+/**
+ * CLAUDE.md hook injector — ensures CLAUDE.md contains an AIWG-managed
+ * marker block with canonical `@WORKSPACE.md` then `@AIWG.md` includes.
+ *
+ * For provider=claude, AIWG.md still gets generated at project root the
+ * same way as for other providers. The difference: claude reads CLAUDE.md
+ * natively (not AGENTS.md), so we need a different bridge — a managed
+ * block inside CLAUDE.md that pulls AIWG.md in via `@-mention`.
+ *
+ * Design:
+ * - Marker block delimits AIWG-managed content; operator content outside
+ *   the block is never touched.
+ * - If CLAUDE.md exists without the block, append the block to the end.
+ * - If CLAUDE.md exists with the block, update the block in place.
+ * - If CLAUDE.md does not exist, create a minimal CLAUDE.md with just
+ *   the marker block (operator will add their own content later).
+ * - `--force` allows replacing the marker block content even when the
+ *   block has been operator-modified inside (with backup).
+ *
+ * @issue #1437
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { buildProviderBootstrapBlock } from './workspace-context.js';
+export const CLAUDE_HOOK_START = '<!-- AIWG:claude-md-hook:start -->';
+export const CLAUDE_HOOK_END = '<!-- AIWG:claude-md-hook:end -->';
+/**
+ * The managed block that gets inserted into CLAUDE.md. Tells Claude Code
+ * to load AIWG.md as the project context entry point. Kept short — the
+ * actual context lives in AIWG.md.
+ */
+export function buildClaudeHookBlock() {
+    return [
+        CLAUDE_HOOK_START,
+        '',
+        buildProviderBootstrapBlock('claude'),
+        '@.aiwg/aiwg.config',
+        '',
+        '<!--',
+        '  This block is managed by `aiwg regenerate` and `aiwg use`.',
+        '  Operator content above and below this block is preserved on regenerate.',
+        '  To change AIWG.md content, edit .aiwg/AIWG.md (the normalized source)',
+        '  then run `aiwg regenerate`.',
+        '-->',
+        '',
+        CLAUDE_HOOK_END,
+    ].join('\n');
+}
+/**
+ * Ensure CLAUDE.md at projectPath contains the AIWG-managed marker block
+ * pointing at AIWG.md. Returns a result describing what was done.
+ */
+export async function ensureClaudeMdHook(projectPath, opts = {}) {
+    const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+    const result = {
+        claudeMdPath,
+        action: 'skipped',
+        warnings: [],
+    };
+    const block = buildClaudeHookBlock();
+    // Case 1: CLAUDE.md does not exist — create a minimal one with just the block.
+    let existing;
+    try {
+        existing = await fs.readFile(claudeMdPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            const minimal = `${block}\n`;
+            await fs.writeFile(claudeMdPath, minimal, 'utf8');
+            result.action = 'created';
+            return result;
+        }
+        throw err;
+    }
+    const startIdx = existing.indexOf(CLAUDE_HOOK_START);
+    const endIdx = existing.indexOf(CLAUDE_HOOK_END);
+    // Case 2: marker block does not exist — append the block to end of file.
+    if (startIdx === -1 && endIdx === -1) {
+        // Ensure the file ends with a single newline before appending.
+        const trimmed = existing.replace(/\n+$/, '\n');
+        const updated = `${trimmed}\n${block}\n`;
+        await fs.writeFile(claudeMdPath, updated, 'utf8');
+        result.action = 'inserted';
+        return result;
+    }
+    // Marker block is present but malformed (one of the two markers missing).
+    if (startIdx === -1 || endIdx === -1) {
+        result.warnings.push(`CLAUDE.md has a malformed AIWG hook block (one marker missing). Re-run with --force to repair.`);
+        if (!opts.force) {
+            return result;
+        }
+        // With --force, back up and append a fresh block.
+        if (opts.detectExistingFiles !== false) {
+            const backupPath = `${claudeMdPath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
+            await fs.writeFile(backupPath, existing, 'utf8');
+            result.backupPath = backupPath;
+        }
+        const trimmed = existing.replace(/\n+$/, '\n');
+        const updated = `${trimmed}\n${block}\n`;
+        await fs.writeFile(claudeMdPath, updated, 'utf8');
+        result.action = 'inserted';
+        return result;
+    }
+    // Case 3: marker block exists — check whether the content matches canonical.
+    const blockEndOffset = endIdx + CLAUDE_HOOK_END.length;
+    const currentBlock = existing.substring(startIdx, blockEndOffset);
+    if (currentBlock === block) {
+        result.action = 'unchanged';
+        return result;
+    }
+    // Block has drifted. Back up first if --force; warn-and-update otherwise
+    // (the block is AIWG-managed, so we update by default; the backup is for
+    // the case where an operator made deliberate edits inside the block).
+    if (opts.force) {
+        const backupPath = `${claudeMdPath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
+        await fs.writeFile(backupPath, existing, 'utf8');
+        result.backupPath = backupPath;
+    }
+    else {
+        result.warnings.push(`CLAUDE.md AIWG hook block has been modified inside the markers; updating to canonical content. Operator content outside the block is preserved.`);
+    }
+    const updated = existing.substring(0, startIdx) + block + existing.substring(blockEndOffset);
+    await fs.writeFile(claudeMdPath, updated, 'utf8');
+    result.action = 'updated';
+    return result;
+}
+//# sourceMappingURL=claude-hook.js.map

package/dist/src/smiths/context-pipeline/discovery.js

@@ -0,0 +1,187 @@
+/**
+ * Deployed-artifact discovery for the context-pipeline.
+ *
+ * Walks the per-provider deploy paths after `aiwg use` has completed and emits
+ * IndexEntry[] arrays for the four canonical AGENTS.md sections (Agents, Rules,
+ * Skills, Behaviors). The generator-runs-after-deploy invariant from ADR-1 §7
+ * means the discovery is filesystem-observed: only files that actually landed
+ * appear in the link index. Failed deploys produce shorter indexes, never
+ * broken links.
+ *
+ * Skill discovery is folder-based (each skill is a directory containing
+ * SKILL.md). Agent/rule/behavior discovery is file-based (each artifact is
+ * one .md file). The asymmetry mirrors the deploy-path conventions defined in
+ * `ProviderDefinition.paths.contextDiscovery`.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)\n---/;
+/**
+ * Read the YAML frontmatter from a markdown file.
+ *
+ * Returns null when the file does not start with frontmatter or the block is
+ * malformed. Discovery callers treat that as "use the basename as id and the
+ * filename as description" rather than aborting — discovery is best-effort.
+ */
+async function readFrontmatter(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        const match = FRONTMATTER_REGEX.exec(content);
+        if (!match)
+            return null;
+        const parsed = yaml.load(match[1]);
+        if (parsed && typeof parsed === 'object') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build an IndexEntry from a markdown file path.
+ *
+ * Returns null when the file is unreadable; otherwise emits an entry with
+ * frontmatter-derived metadata (falling back to filename basename for `id`
+ * and a placeholder description if neither is available).
+ */
+async function entryFromFile(absolutePath, relativePath) {
+    try {
+        const stat = await fs.stat(absolutePath);
+        if (!stat.isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const fm = await readFrontmatter(absolutePath);
+    const basename = path.basename(absolutePath, path.extname(absolutePath));
+    const id = fm?.name?.trim() || basename;
+    const description = fm?.description?.trim() || `(no description)`;
+    const tags = Array.isArray(fm?.tags)
+        ? fm.tags
+        : typeof fm?.tags === 'string'
+            ? fm.tags.split(',').map((t) => t.trim()).filter(Boolean)
+            : [];
+    const safetyCritical = fm?.['safety-critical'] === true;
+    // Always emit forward slashes in the path so AGENTS.md is portable across
+    // platforms that read it (Codex on Linux, Cursor on Windows, etc.).
+    const portablePath = relativePath.replace(/\\/g, '/');
+    return {
+        id,
+        description,
+        path: portablePath,
+        tags: tags.length > 0 ? tags : undefined,
+        safetyCritical: safetyCritical || undefined,
+    };
+}
+/**
+ * Build an IndexEntry from a skill folder.
+ *
+ * Skills are folders containing SKILL.md (the convention enforced across all
+ * platform skill paths). The folder name is the id when no frontmatter `name`
+ * is present.
+ */
+async function entryFromSkillFolder(folderAbsPath, folderRelPath) {
+    const skillFile = path.join(folderAbsPath, 'SKILL.md');
+    try {
+        const stat = await fs.stat(skillFile);
+        if (!stat.isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const skillRelPath = path.posix.join(folderRelPath.replace(/\\/g, '/'), 'SKILL.md');
+    const entry = await entryFromFile(skillFile, skillRelPath);
+    if (!entry)
+        return null;
+    // Folder name takes precedence as id when frontmatter `name` isn't set —
+    // skill folders are addressed by directory, not by SKILL.md filename.
+    const folderName = path.basename(folderAbsPath);
+    if (!entry.id || entry.id === 'SKILL') {
+        entry.id = folderName;
+    }
+    return entry;
+}
+/**
+ * List markdown files in a directory (non-recursive).
+ *
+ * Returns an empty array if the directory does not exist or is empty. This
+ * is intentional — discovery never errors on missing paths because providers
+ * legitimately deploy nothing in some categories (e.g., OpenCode commands).
+ */
+async function listMarkdownFiles(dirAbs) {
+    try {
+        const entries = await fs.readdir(dirAbs, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile() && (e.name.endsWith('.md') || e.name.endsWith('.agent.md')))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * List skill subfolders in a directory (non-recursive).
+ */
+async function listSkillFolders(dirAbs) {
+    try {
+        const entries = await fs.readdir(dirAbs, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Discover one section's deployed artifacts.
+ *
+ * Type determines whether to scan files (agents/rules/behaviors) or folders
+ * (skills). Empty `relativeDir` short-circuits to an empty section.
+ */
+export async function discoverSection(type, projectPath, relativeDir) {
+    if (!relativeDir) {
+        return { type, entries: [] };
+    }
+    // Allow absolute paths (home-dir providers like OpenClaw, ~/.codex/skills).
+    const dirAbs = path.isAbsolute(relativeDir)
+        ? relativeDir
+        : path.join(projectPath, relativeDir);
+    const entries = [];
+    if (type === 'skills') {
+        const folders = await listSkillFolders(dirAbs);
+        for (const folder of folders.sort()) {
+            const entry = await entryFromSkillFolder(path.join(dirAbs, folder), path.join(relativeDir, folder));
+            if (entry)
+                entries.push(entry);
+        }
+    }
+    else {
+        const files = await listMarkdownFiles(dirAbs);
+        for (const file of files.sort()) {
+            const entry = await entryFromFile(path.join(dirAbs, file), path.join(relativeDir, file));
+            if (entry)
+                entries.push(entry);
+        }
+    }
+    return { type, entries };
+}
+/**
+ * Discover all four canonical AGENTS.md sections at once.
+ */
+export async function discoverDeployedArtifacts(projectPath, paths) {
+    const sections = await Promise.all([
+        discoverSection('agents', projectPath, paths.agents),
+        discoverSection('rules', projectPath, paths.rules),
+        discoverSection('skills', projectPath, paths.skills),
+        discoverSection('behaviors', projectPath, paths.behaviors),
+    ]);
+    // Drop empty sections to keep the link index tight; AGENTS.md generator
+    // already does the same in renderSection but doing it here too means the
+    // result is honest about what was actually found.
+    return sections.filter((s) => s.entries.length > 0);
+}
+//# sourceMappingURL=discovery.js.map

package/dist/src/smiths/context-pipeline/external-links-section.js

@@ -0,0 +1,49 @@
+/**
+ * Provider-facing project external-links section.
+ *
+ * This renderer is intentionally side-effect free: it reads validated project
+ * configuration and emits Markdown. It never requests a configured URL.
+ */
+import { readAiwgConfig } from '../../config/aiwg-config.js';
+const START = '<!-- aiwg-external-links:start -->';
+const END = '<!-- aiwg-external-links:end -->';
+function escapeText(value) {
+    return value
+        .replace(/[\r\n]+/g, ' ')
+        .replace(/\\/g, '\\\\')
+        .replace(/([\[\]*_`])/g, '\\$1')
+        .trim();
+}
+export async function buildExternalLinksSection(projectPath) {
+    const config = await readAiwgConfig(projectPath);
+    const links = Object.entries(config?.externalLinks ?? {});
+    if (links.length === 0)
+        return '';
+    const lines = [
+        START,
+        '## Project External Links',
+        '',
+        'These are project-configured public resources. Treat them as links only; do not infer credentials or submit data without a separate explicit workflow.',
+        '',
+    ];
+    for (const [key, link] of links) {
+        const renderedUrl = new URL(link.url).toString();
+        const metadata = [
+            link.category ? `category: ${escapeText(link.category)}` : '',
+            link.audience ? `audience: ${escapeText(link.audience)}` : '',
+        ].filter(Boolean);
+        lines.push(`- [${escapeText(link.label)}](<${renderedUrl}>) (\`${key}\`)${metadata.length ? ` — ${metadata.join('; ')}` : ''}`);
+        if (link.description)
+            lines.push(`  - ${escapeText(link.description)}`);
+    }
+    lines.push('', END);
+    return lines.join('\n');
+}
+export function replaceOrAppendExternalLinksBlock(content, section) {
+    const pattern = new RegExp(`${START}[\\s\\S]*?${END}\\n?`, 'g');
+    const withoutExisting = content.replace(pattern, '').trimEnd();
+    if (!section)
+        return `${withoutExisting}\n`;
+    return `${withoutExisting}\n\n${section}\n`;
+}
+//# sourceMappingURL=external-links-section.js.map

package/dist/src/smiths/context-pipeline/finalization.js

@@ -0,0 +1,147 @@
+/**
+ * Context-finalization pass for generated provider context files.
+ *
+ * Templates provide the stable structure; this pass stitches in current
+ * workspace facts from `.aiwg/aiwg.config` and the discover-first protocol so
+ * provider context files do not remain template-only (#1365).
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readAiwgConfig } from '../../config/aiwg-config.js';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { renderTrackerProtocol, resolveTrackerAuthority } from '../../tracker/capability-protocol.js';
+import { buildExternalLinksSection, replaceOrAppendExternalLinksBlock, } from './external-links-section.js';
+export const FINALIZATION_START = '<!-- aiwg-context-finalization:START -->';
+export const FINALIZATION_END = '<!-- aiwg-context-finalization:END -->';
+const AIWG_SIGNATURE_COMMENT = '<!-- aiwg-managed -->';
+const execFileAsync = promisify(execFile);
+function formatList(values) {
+    return values.length > 0 ? values.join(', ') : 'none recorded';
+}
+async function readConfig(projectPath) {
+    try {
+        return await readAiwgConfig(projectPath);
+    }
+    catch {
+        return null;
+    }
+}
+async function readGitRemoteUrls(projectPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', projectPath, 'remote', '-v'], {
+            maxBuffer: 1024 * 1024,
+        });
+        const urls = {};
+        for (const line of stdout.split(/\r?\n/)) {
+            const match = line.match(/^(\S+)\s+(\S+)\s+\((fetch|push)\)$/);
+            if (!match)
+                continue;
+            const [, name, url, direction] = match;
+            if (direction === 'fetch' || !urls[name])
+                urls[name] = url;
+        }
+        return urls;
+    }
+    catch {
+        return {};
+    }
+}
+function displayProjectPath(projectPath, targetPath) {
+    const relative = path.relative(projectPath, targetPath).replace(/\\/g, '/');
+    if (relative && !relative.startsWith('..') && !path.isAbsolute(relative))
+        return relative;
+    return targetPath;
+}
+export async function buildContextFinalizationBlock(projectPath) {
+    const config = await readConfig(projectPath);
+    const remoteUrls = await readGitRemoteUrls(projectPath);
+    const providers = config?.providers ?? [];
+    const installed = Object.entries(config?.installed ?? {});
+    const installedNames = installed.map(([name]) => name);
+    const providerDeployments = new Set();
+    const normalizedAiwgMdPath = displayProjectPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
+    for (const [, entry] of installed) {
+        for (const provider of Object.keys(entry.deployedTo ?? {})) {
+            providerDeployments.add(provider);
+        }
+    }
+    const lines = [
+        FINALIZATION_START,
+        '## Context Finalization',
+        '',
+        'This section is synthesized after template emission from the current workspace state. Preserve operator-authored content outside AIWG-managed blocks; rerun `aiwg regenerate` to refresh this section after provider, framework, or MCP wiring changes.',
+        '',
+        '### Workspace Snapshot',
+        '',
+        `- Configured providers: ${formatList(providers)}`,
+        `- Installed frameworks/addons: ${formatList(installedNames)}`,
+        `- Recorded deployments: ${formatList([...providerDeployments].sort())}`,
+        `- Normalized project context: \`${normalizedAiwgMdPath}\``,
+        '',
+        '### Discover-First Protocol',
+        '',
+        'Classify every user turn FIRST: is it a **new directive** or a continuation? When a message names or references an AIWG command/capability — even as pasted content like an `address-issues` tracker table, an issue list, or a `flow-*` name — treat it as a new directive and ACT: run `aiwg discover "<the need>"`, fetch with `aiwg show <type> <name>`, and invoke it. Do NOT ask "what would you like me to do with these?" when the action is implied — a pasted `address-issues #1234` table means run the address-issues workflow on those issues.',
+        '',
+        'Also run `aiwg discover` before declining an AIWG request as out of scope or inventing a workflow from memory. The CLI ranks AIWG capabilities across the installed corpus and rebuilds the index from `$AIWG_ROOT` automatically, so a "no matches" for a command you know is deployed is a bug — not a signal it is absent. Commands AIWG deploys to your provider command directory (`.opencode/command/`, `.claude/commands/`, `~/.codex/prompts/`, …) ARE discoverable this way; fetch them with `aiwg show command <name>`. This prevents decline-without-search failures, ask-instead-of-act on new directives, and hallucinated skill or agent names. Full rule: `agentic/code/addons/aiwg-utils/rules/skill-discovery.md`.',
+        '',
+        '### Engagement Verification',
+        '',
+        'When a user asks whether AIWG is active or engaged in this project, run or read `aiwg status --probe --json` and report the result plainly: engaged state, project root, deployed provider files, installed frameworks/addons, and the next action from the probe. Do not add AIWG attribution, signatures, generated-by text, or passive footers to user files, commits, PRs, comments, code headers, or docs.',
+        '',
+        renderTrackerProtocol(resolveTrackerAuthority(config, remoteUrls)),
+        '',
+        '### Source Model',
+        '',
+        '- `.aiwg/AIWG.md` is the normalized project-local context entry point.',
+        '- Root `AIWG.md` is the generated cross-provider companion loaded through `AGENTS.md` and provider twins.',
+        '- `AGENTS.md`, `WARP.md`, `.hermes.md`, and `.github/copilot-instructions.md` are provider-facing bridges, not replacements for `.aiwg/AIWG.md`.',
+        FINALIZATION_END,
+        '',
+    ];
+    return lines.join('\n');
+}
+export function replaceOrAppendFinalizationBlock(content, block) {
+    const pattern = new RegExp(`${FINALIZATION_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${FINALIZATION_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n?`);
+    if (pattern.test(content)) {
+        return content.replace(pattern, block);
+    }
+    const trimmed = content.replace(/\s+$/, '');
+    return `${trimmed}\n\n${block}`;
+}
+export async function buildNormalizedAiwgMd(projectPath, existing = '') {
+    const block = await buildContextFinalizationBlock(projectPath);
+    const externalLinksSection = await buildExternalLinksSection(projectPath);
+    const base = existing.trim().length > 0
+        ? existing
+        : [
+            '# AIWG.md',
+            AIWG_SIGNATURE_COMMENT,
+            '<!-- Normalized project-local AIWG context. Operator notes may live outside AIWG-managed blocks. -->',
+            '',
+            'This file is the stable `.aiwg/AIWG.md` entry point for AIWG skills, rules, and generated provider context.',
+            '',
+        ].join('\n');
+    const signed = base.includes(AIWG_SIGNATURE_COMMENT)
+        ? base
+        : base.replace(/^([^\n]*)(\n|$)/, `$1\n${AIWG_SIGNATURE_COMMENT}\n`);
+    const withFinalization = replaceOrAppendFinalizationBlock(signed, block);
+    return replaceOrAppendExternalLinksBlock(withFinalization, externalLinksSection);
+}
+export async function writeNormalizedAiwgMd(projectPath) {
+    const targetPath = projectAiwgPath(projectPath, 'AIWG.md');
+    let existing = '';
+    try {
+        existing = await fs.readFile(targetPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    const content = await buildNormalizedAiwgMd(projectPath, existing);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content.endsWith('\n') ? content : `${content}\n`, 'utf8');
+    return targetPath;
+}
+//# sourceMappingURL=finalization.js.map