@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/extensions/project-local-scaffold.js

@@ -0,0 +1,252 @@
+/**
+ * Project-Local Bundle Scaffolding
+ *
+ * Creates a complete `.aiwg/<type>/<name>/` bundle with a valid manifest,
+ * a starter artifact (skill or rule), and a README that includes the
+ * identical-form portability reminder.
+ *
+ * The output is byte-identical-shaped to upstream addon directories so
+ * `aiwg promote` can graduate it without any rewrite.
+ *
+ * @design @.aiwg/architecture/adr-identical-form-portability.md (#1038)
+ * @implements #1050
+ */
+import { mkdir, writeFile, stat } from 'fs/promises';
+import { join } from 'path';
+import { projectAiwgPath } from '../config/project-artifacts.js';
+import { PROJECT_LOCAL_TYPE_TO_DIR as TYPE_TO_DIR } from './project-local-paths.js';
+const NAME_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+function buildManifest(opts) {
+    const { type, name, description = `Project-local ${type} '${name}'` } = opts;
+    const base = {
+        id: name,
+        type,
+        name,
+        version: '0.1.0',
+        description,
+        manifestVersion: '1',
+        platforms: { claude: 'full' },
+        keywords: [type, 'project-local'],
+        deployment: { pathTemplate: '.{platform}/skills/{id}.md' },
+    };
+    if (type === 'addon') {
+        base['addonConfig'] = { entry: { skills: 'skills/' } };
+    }
+    else if (type === 'framework') {
+        base['frameworkConfig'] = { path: 'src/' };
+    }
+    else if (type === 'plugin') {
+        base['pluginConfig'] = { payloadType: 'addon', payloadPath: 'payload/' };
+    }
+    else if (type === 'provider') {
+        base['providerConfig'] = { extends: 'claude', displayName: name };
+    }
+    return base;
+}
+function readme(opts) {
+    const { type, name, description = '' } = opts;
+    const usage = type === 'provider'
+        ? `Select this provider while deploying a framework:
+\`\`\`bash
+aiwg use sdlc --provider ${name}
+\`\`\``
+        : `Deploy to your configured providers:
+\`\`\`bash
+aiwg use ${name}
+\`\`\``;
+    const upstreamDir = type === 'provider' ? 'providers' : 'addons';
+    return `# ${name}
+
+${description || `Project-local ${type} bundle.`}
+
+## What this is
+
+A project-local AIWG ${type} living under \`.aiwg/${TYPE_TO_DIR[type]}/${name}/\`.
+Discovered automatically by \`aiwg use\`${type === 'provider' ? ' as a provider alias.' : ' and deployed alongside upstream artifacts.'}
+
+## Layout
+
+\`\`\`
+.aiwg/${TYPE_TO_DIR[type]}/${name}/
+├── manifest.json          # Bundle metadata (validated by aiwg)
+├── README.md              # This file
+└── ${type === 'framework' ? 'src/' : type === 'plugin' ? 'payload/' : type === 'provider' ? 'manifest.json only' : 'skills/ or rules/'}
+\`\`\`
+
+## Usage
+
+${usage}
+
+Inspect health:
+\`\`\`bash
+aiwg doctor --project-local
+\`\`\`
+
+Remove (preserves source under \`.aiwg/\`):
+\`\`\`bash
+aiwg remove ${name}
+\`\`\`
+
+## Identical-form portability
+
+This directory is shaped **byte-identical** to upstream
+\`agentic/code/${upstreamDir}/${name}/\`. To graduate, run:
+
+\`\`\`bash
+aiwg promote ${name} --dry-run     # preview
+aiwg promote ${name}                # copy to upstream
+aiwg promote ${name} --to corpus ~/my-corpus/   # or to a private corpus
+\`\`\`
+
+Keep this directory shaped like upstream so \`aiwg promote\` works.
+
+## Customization tips
+
+- Edit \`manifest.json\` to set a real \`description\`, bump \`version\` to
+  \`1.0.0\` when stable, and add platforms beyond \`claude\` if needed.
+- Add new artifacts under \`skills/\`, \`rules/\`, \`agents/\`, or \`commands/\`
+  per AIWG conventions.
+- Use \`@\`-references for cross-artifact links: \`@$AIWG_ROOT/...\` for
+  upstream paths, \`@.aiwg/...\` for project-local references (note: the
+  latter will block promotion unless \`--force\` is passed).
+
+## See also
+
+- \`docs/customization/project-local-quickstart.md\` — first bundle in 5 minutes
+- \`docs/customization/project-local-lifecycle.md\` — full lifecycle reference
+- \`docs/customization/extensions-vs-addons-vs-frameworks-vs-plugins.md\` — pick the right type
+`;
+}
+const STARTER_SKILL = (name) => `---
+name: ${name}-skill
+description: Starter skill for the ${name} project-local bundle. Customize this.
+commandHint:
+  modelRole: efficiency
+  modelTier: economy
+---
+
+# ${name}-skill
+
+Replace this body with the workflow your skill performs.
+
+## When to use
+
+Describe the trigger conditions for this skill.
+
+## Steps
+
+1. Step one
+2. Step two
+
+<!-- TIP: keep front-matter \`name\` matching the file basename for predictable -->
+<!-- TIP: deploy paths and traceability with the SKILL.md frontmatter schema. -->
+`;
+const STARTER_RULE = (name) => `---
+id: ${name}-rule
+---
+
+# ${name}-rule
+
+Describe the rule. Keep it concise — rules are loaded into every relevant
+agent context, so terseness pays off.
+
+## Why
+
+Explain the motivation. Future-you will thank you.
+
+## How to apply
+
+State when this rule fires and what action it requires.
+`;
+const STARTER_AGENT = (name) => `---
+name: ${name}-agent
+description: Starter agent for the ${name} project-local bundle.
+model-role: efficiency
+model-tier: economy
+---
+
+# ${name}-agent
+
+You are a specialist for [domain]. Customize this body with the agent's
+focus, allowed tools, and termination conditions.
+`;
+export async function scaffoldProjectLocalBundle(options) {
+    const projectDir = options.projectDir ?? process.cwd();
+    const refuseOnExists = options.refuseOnExists ?? true;
+    const dryRun = options.dryRun ?? false;
+    if (!NAME_REGEX.test(options.name)) {
+        throw new Error(`Invalid bundle name '${options.name}': must be kebab-case (a-z, 0-9, '-'), no leading/trailing hyphen.`);
+    }
+    const dirName = TYPE_TO_DIR[options.type];
+    const bundlePath = projectAiwgPath(projectDir, dirName, options.name);
+    // Refuse to overwrite
+    try {
+        await stat(bundlePath);
+        if (refuseOnExists) {
+            return { bundlePath, filesCreated: [], alreadyExists: true, dryRun };
+        }
+    }
+    catch {
+        // Doesn't exist — good
+    }
+    if (dryRun) {
+        // Compute the file list without writing anything.
+        const starter = options.starter ?? (options.type === 'framework' || options.type === 'plugin' || options.type === 'provider' ? 'minimal' : 'skill');
+        const filesCreated = ['manifest.json', 'README.md'];
+        if (starter === 'skill')
+            filesCreated.push(`skills/${options.name}-skill/SKILL.md`);
+        else if (starter === 'rule')
+            filesCreated.push(`rules/${options.name}.md`);
+        else if (starter === 'agent')
+            filesCreated.push(`agents/${options.name}.md`);
+        if (options.type === 'framework')
+            filesCreated.push('src/.gitkeep');
+        if (options.type === 'plugin')
+            filesCreated.push('payload/.gitkeep');
+        return { bundlePath, filesCreated, alreadyExists: false, dryRun: true };
+    }
+    await mkdir(bundlePath, { recursive: true });
+    const filesCreated = [];
+    // Pick starter
+    const starter = options.starter ?? (options.type === 'framework' || options.type === 'plugin' || options.type === 'provider' ? 'minimal' : 'skill');
+    // manifest.json
+    const manifest = buildManifest(options);
+    await writeFile(join(bundlePath, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    filesCreated.push('manifest.json');
+    // README.md
+    await writeFile(join(bundlePath, 'README.md'), readme(options), 'utf-8');
+    filesCreated.push('README.md');
+    // Starter artifact
+    if (starter === 'skill') {
+        const skillDir = join(bundlePath, 'skills', `${options.name}-skill`);
+        await mkdir(skillDir, { recursive: true });
+        await writeFile(join(skillDir, 'SKILL.md'), STARTER_SKILL(options.name), 'utf-8');
+        filesCreated.push(`skills/${options.name}-skill/SKILL.md`);
+    }
+    else if (starter === 'rule') {
+        const rulesDir = join(bundlePath, 'rules');
+        await mkdir(rulesDir, { recursive: true });
+        await writeFile(join(rulesDir, `${options.name}.md`), STARTER_RULE(options.name), 'utf-8');
+        filesCreated.push(`rules/${options.name}.md`);
+    }
+    else if (starter === 'agent') {
+        const agentsDir = join(bundlePath, 'agents');
+        await mkdir(agentsDir, { recursive: true });
+        await writeFile(join(agentsDir, `${options.name}.md`), STARTER_AGENT(options.name), 'utf-8');
+        filesCreated.push(`agents/${options.name}.md`);
+    }
+    // 'minimal' = no starter artifact (operator fills it in)
+    // Type-specific stub directories
+    if (options.type === 'framework') {
+        await mkdir(join(bundlePath, 'src'), { recursive: true });
+        await writeFile(join(bundlePath, 'src', '.gitkeep'), '# Framework source files go here\n', 'utf-8');
+        filesCreated.push('src/.gitkeep');
+    }
+    if (options.type === 'plugin') {
+        await mkdir(join(bundlePath, 'payload'), { recursive: true });
+        await writeFile(join(bundlePath, 'payload', '.gitkeep'), '# Plugin payload files go here\n', 'utf-8');
+        filesCreated.push('payload/.gitkeep');
+    }
+    return { bundlePath, filesCreated, alreadyExists: false };
+}
+//# sourceMappingURL=project-local-scaffold.js.map

package/dist/src/extensions/project-quickref.js

@@ -0,0 +1,291 @@
+/**
+ * Canonical project quickref generation and provider-aware deployment.
+ *
+ * The committed source is `.aiwg/quickref.json`. Generated and provider
+ * copies are expendable and carry ownership markers so stale copies can be
+ * removed without touching operator-authored skills.
+ */
+import { createHash } from 'crypto';
+import { access, mkdir, readFile, readdir, rm, writeFile } from 'fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { homedir } from 'os';
+import { z } from 'zod';
+import { getProviderDefinition, normalizeProviderDefinitionId, } from '../providers/provider-definitions.js';
+import { OPERATIONAL_SHOW_TYPES } from '../artifacts/types.js';
+import { projectAiwgPath } from '../config/project-artifacts.js';
+import { appendAiwgSourceTrackBlock } from './project-local-gitignore.js';
+const OWNERSHIP_MARKER = '.aiwg-project-quickref.json';
+const ShowHintSchema = z.object({
+    type: z.enum(OPERATIONAL_SHOW_TYPES),
+    name: z.string().min(1).max(128),
+}).strict();
+const QuickrefEntrySchema = z.object({
+    title: z.string().min(1).max(128),
+    summary: z.string().min(1).max(512),
+    discover: z.array(z.string().min(1).max(256)).max(10).default([]),
+    show: z.array(ShowHintSchema).max(20).default([]),
+}).strict().refine(entry => entry.discover.length > 0 || entry.show.length > 0, { message: 'each entry must provide at least one discover or show hint' });
+export const ProjectQuickrefSchema = z.object({
+    version: z.literal('1'),
+    project: z.object({
+        id: z.string().regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'must be kebab-case'),
+        name: z.string().min(1).max(128),
+        description: z.string().min(1).max(512),
+    }).strict(),
+    precedence: z.string().min(1).max(1024),
+    entries: z.array(QuickrefEntrySchema).min(1).max(50),
+}).strict();
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+async function readIfPresent(filePath) {
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function projectQuickrefSkillName(projectId) {
+    return `aiwg-project-${projectId}-quickref`;
+}
+export async function loadProjectQuickref(projectDir) {
+    const sourcePath = projectAiwgPath(projectDir, 'quickref.json');
+    let raw;
+    try {
+        raw = await readFile(sourcePath, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        return {
+            sourcePath,
+            errors: code === 'ENOENT' ? [] : [`${sourcePath}: ${error.message}`],
+            exists: code !== 'ENOENT',
+        };
+    }
+    try {
+        const parsed = ProjectQuickrefSchema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            return {
+                sourcePath,
+                exists: true,
+                errors: parsed.error.issues.map(issue => `${sourcePath}: ${issue.path.join('.') || '(root)'}: ${issue.message}`),
+            };
+        }
+        return { sourcePath, definition: parsed.data, errors: [], exists: true };
+    }
+    catch (error) {
+        return { sourcePath, errors: [`${sourcePath}: invalid JSON: ${error.message}`], exists: true };
+    }
+}
+export function renderProjectQuickref(definition) {
+    const skillName = projectQuickrefSkillName(definition.project.id);
+    const lines = [
+        '---',
+        `name: ${skillName}`,
+        `description: ${JSON.stringify(`Project-specific orientation for ${definition.project.name}`)}`,
+        'kernel: true',
+        'platforms: [all]',
+        '---',
+        '',
+        `# ${definition.project.name} Quick Reference`,
+        '',
+        definition.project.description,
+        '',
+        '## Precedence',
+        '',
+        definition.precedence,
+        '',
+    ];
+    for (const entry of definition.entries) {
+        lines.push(`## ${entry.title}`, '', entry.summary, '');
+        for (const phrase of entry.discover) {
+            lines.push(`- Discover: \`aiwg discover ${JSON.stringify(phrase)}\``);
+        }
+        for (const hint of entry.show) {
+            lines.push(`- Fetch: \`aiwg show ${hint.type} ${hint.name}\``);
+        }
+        lines.push('');
+    }
+    lines.push('The quickref is an orientation layer. Retrieve the indexed project asset before applying its full workflow.', '');
+    return lines.join('\n');
+}
+export async function generateProjectQuickref(projectDir, options = {}) {
+    const loaded = await loadProjectQuickref(projectDir);
+    if (!loaded.exists)
+        throw new Error(`Project quickref source not found: ${loaded.sourcePath}`);
+    if (!loaded.definition)
+        throw new Error(loaded.errors.join('\n'));
+    if (!options.dryRun)
+        await appendAiwgSourceTrackBlock(projectDir);
+    const skillName = projectQuickrefSkillName(loaded.definition.project.id);
+    const outputPath = projectAiwgPath(projectDir, 'generated', 'project-quickref', skillName, 'SKILL.md');
+    const content = renderProjectQuickref(loaded.definition);
+    const current = await readIfPresent(outputPath);
+    const changed = current !== content;
+    if (!options.dryRun && changed) {
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, content, 'utf8');
+    }
+    if (!options.dryRun) {
+        const generatedRoot = projectAiwgPath(projectDir, 'generated', 'project-quickref');
+        try {
+            const entries = await readdir(generatedRoot, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory() && entry.name !== skillName) {
+                    await rm(join(generatedRoot, entry.name), { recursive: true });
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return {
+        sourcePath: loaded.sourcePath,
+        outputPath,
+        skillName,
+        content,
+        changed,
+        dryRun: options.dryRun ?? false,
+    };
+}
+function resolveProviderSkillsRoot(provider, projectDir, homeDir) {
+    const normalized = normalizeProviderDefinitionId(provider);
+    if (!normalized)
+        throw new Error(`Unknown provider '${provider}'`);
+    const definition = getProviderDefinition(normalized);
+    if (!definition)
+        throw new Error(`Provider definition unavailable for '${provider}'`);
+    const configured = definition.paths.kernelSkills ?? definition.paths.artifacts.skills;
+    if (!configured)
+        throw new Error(`Provider '${normalized}' has no supported skill or aggregation target`);
+    const expanded = configured === '~'
+        ? homeDir
+        : configured.startsWith('~/')
+            ? join(homeDir, configured.slice(2))
+            : configured;
+    return {
+        provider: normalized,
+        root: isAbsolute(expanded) ? expanded : resolve(projectDir, expanded),
+        emulated: definition.paths.kernelSkills === null,
+        global: definition.paths.deployTarget === 'home' || configured.startsWith('~/'),
+    };
+}
+async function readOwnershipMarker(skillDir) {
+    const raw = await readIfPresent(join(skillDir, OWNERSHIP_MARKER));
+    if (!raw)
+        return null;
+    try {
+        const marker = JSON.parse(raw);
+        return marker.version === 1 ? marker : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function findStaleOwnedQuickrefs(root, projectDir, keepName, global) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const stale = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === keepName)
+            continue;
+        const candidate = join(root, entry.name);
+        const marker = await readOwnershipMarker(candidate);
+        if (marker && (!global || marker.sourceProject === resolve(projectDir)))
+            stale.push(candidate);
+    }
+    return stale;
+}
+export async function deployProjectQuickref(projectDir, provider, options = {}) {
+    const generated = await generateProjectQuickref(projectDir, { dryRun: options.dryRun });
+    const loaded = await loadProjectQuickref(projectDir);
+    if (!loaded.definition)
+        throw new Error(loaded.errors.join('\n'));
+    const target = resolveProviderSkillsRoot(provider, projectDir, options.homeDir ?? homedir());
+    const targetDir = join(target.root, generated.skillName);
+    const targetPath = join(targetDir, 'SKILL.md');
+    const existingMarker = await readOwnershipMarker(targetDir);
+    try {
+        await access(targetDir);
+        if (!existingMarker) {
+            throw new Error(`Refusing to replace operator-owned skill directory: ${targetDir}`);
+        }
+        if (existingMarker.projectId !== loaded.definition.project.id ||
+            (target.global && existingMarker.sourceProject !== resolve(projectDir))) {
+            throw new Error(`Project quickref collision at ${targetDir}; project id '${loaded.definition.project.id}' is already owned by ${existingMarker.sourceProject}`);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const marker = {
+        version: 1,
+        projectId: loaded.definition.project.id,
+        sourceProject: resolve(projectDir),
+        sourcePath: loaded.sourcePath,
+        contentHash: sha256(generated.content),
+    };
+    const markerContent = JSON.stringify(marker, null, 2) + '\n';
+    const currentContent = await readIfPresent(targetPath);
+    const currentMarker = await readIfPresent(join(targetDir, OWNERSHIP_MARKER));
+    const changed = currentContent !== generated.content || currentMarker !== markerContent;
+    const stale = await findStaleOwnedQuickrefs(target.root, projectDir, generated.skillName, target.global);
+    if (!options.dryRun) {
+        for (const stalePath of stale)
+            await rm(stalePath, { recursive: true });
+        if (changed) {
+            await mkdir(targetDir, { recursive: true });
+            await writeFile(targetPath, generated.content, 'utf8');
+            await writeFile(join(targetDir, OWNERSHIP_MARKER), markerContent, 'utf8');
+        }
+    }
+    return {
+        provider: target.provider,
+        targetPath,
+        skillName: generated.skillName,
+        changed,
+        pruned: stale,
+        emulated: target.emulated,
+        dryRun: options.dryRun ?? false,
+    };
+}
+export async function auditProjectQuickref(projectDir, providers, options = {}) {
+    const loaded = await loadProjectQuickref(projectDir);
+    if (!loaded.exists)
+        return { exists: false, errors: loaded.errors, drift: [] };
+    if (!loaded.definition)
+        return { exists: true, errors: loaded.errors, drift: [] };
+    const content = renderProjectQuickref(loaded.definition);
+    const skillName = projectQuickrefSkillName(loaded.definition.project.id);
+    const generatedPath = projectAiwgPath(projectDir, 'generated', 'project-quickref', skillName, 'SKILL.md');
+    const drift = [];
+    if (await readIfPresent(generatedPath) !== content) {
+        drift.push(`generated quickref is missing or stale: ${generatedPath}`);
+    }
+    for (const provider of providers) {
+        try {
+            const target = resolveProviderSkillsRoot(provider, projectDir, options.homeDir ?? homedir());
+            const deployed = join(target.root, skillName, 'SKILL.md');
+            if (await readIfPresent(deployed) !== content) {
+                drift.push(`${target.provider}: deployed quickref is missing or stale: ${deployed}`);
+            }
+        }
+        catch (error) {
+            drift.push(`${provider}: ${error.message}`);
+        }
+    }
+    return { exists: true, errors: [], drift, skillName };
+}
+export function projectQuickrefSourcePath(projectDir) {
+    return projectAiwgPath(projectDir, 'quickref.json');
+}
+//# sourceMappingURL=project-quickref.js.map