@aifabrix/builder 2.53.1 → 2.55.0

package/README.md

@@ -38,6 +38,14 @@ npm install -g @aifabrix/builder
 
 **Alias:** You can use `af` instead of `aifabrix` in any command.
 
+Customer integration repositories can install the Agent Kit (Cursor, Codex, and Claude Code) with:
+
+```bash
+aifabrix agent-kit install
+```
+
+See [Agent Kit commands](docs/commands/agent-kit.md).
+
 ---
 
 ## Goal 1: Install the platform (one command)

package/bin/aifabrix.js

@@ -17,6 +17,7 @@ const { Command } = require('commander');
 const cli = require('../lib/cli');
 const logger = require('../lib/utils/logger');
 const { buildCategorizedHelp } = require('../lib/utils/help-builder');
+const { rewriteClusteredNameFlag } = require('../lib/utils/rewrite-name-flag');
 const packageJson = require('../package.json');
 
 /**
@@ -47,8 +48,7 @@ More:
     return buildCategorizedHelp(program) + ROOT_HELP_FOOTER;
   };
 
-  // Parse command line arguments
-  program.parse();
+  program.parse(rewriteClusteredNameFlag(process.argv));
 }
 
 // TODO: Add error handling for CLI initialization

package/lib/agent-kit/apply-ops.js

@@ -0,0 +1,82 @@
+/**
+ * Apply planned Agent Kit file operations.
+ * @fileoverview Create, replace, append, or delete managed files
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { ACTION } = require('./constants');
+const { wrapSection, appendManagedSection, replaceManagedSection } = require('./managed-section');
+
+/**
+ * @param {string} filePath
+ * @returns {void}
+ */
+function ensureParent(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+/**
+ * @param {object} item
+ * @returns {void}
+ */
+function applyCreate(item) {
+  ensureParent(item.targetAbs);
+  const body =
+    item.mode === 'managed-section' ? wrapSection(item.sourceText) : item.sourceText;
+  fs.writeFileSync(item.targetAbs, body, 'utf8');
+}
+
+/**
+ * @param {object} item
+ * @returns {void}
+ */
+function applyReplace(item) {
+  ensureParent(item.targetAbs);
+  if (item.mode === 'managed-section') {
+    const existing = fs.existsSync(item.targetAbs) ? fs.readFileSync(item.targetAbs, 'utf8') : '';
+    fs.writeFileSync(item.targetAbs, replaceManagedSection(existing, item.sourceText), 'utf8');
+    return;
+  }
+  fs.writeFileSync(item.targetAbs, item.sourceText, 'utf8');
+}
+
+/**
+ * @param {object} item
+ * @returns {void}
+ */
+function applyAppend(item) {
+  const existing = fs.existsSync(item.targetAbs) ? fs.readFileSync(item.targetAbs, 'utf8') : '';
+  ensureParent(item.targetAbs);
+  fs.writeFileSync(item.targetAbs, appendManagedSection(existing, item.sourceText), 'utf8');
+}
+
+/**
+ * @param {object} item
+ * @returns {void}
+ */
+function applyOne(item) {
+  if (item.action === ACTION.CREATE) {
+    applyCreate(item);
+  } else if (item.action === ACTION.REPLACE) {
+    applyReplace(item);
+  } else if (item.action === ACTION.APPEND_SECTION) {
+    applyAppend(item);
+  } else if (item.action === ACTION.DELETE) {
+    fs.unlinkSync(item.targetAbs);
+  }
+}
+
+/**
+ * @param {object[]} ops
+ * @returns {void}
+ */
+function applyOps(ops) {
+  for (const item of ops) {
+    applyOne(item);
+  }
+}
+
+module.exports = { applyOps, applyOne, applyCreate, applyReplace, applyAppend };

package/lib/agent-kit/checksums.js

@@ -0,0 +1,28 @@
+/**
+ * SHA-256 helpers for Agent Kit file classification.
+ * @fileoverview Content hashes for managed files
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('../internal/fs-real-sync');
+
+/**
+ * @param {Buffer|string} value
+ * @returns {string}
+ */
+function sha256(value) {
+  const buf = Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'utf8');
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * @param {string} filePath
+ * @returns {string}
+ */
+function sha256File(filePath) {
+  return sha256(fs.readFileSync(filePath));
+}
+
+module.exports = { sha256, sha256File };

package/lib/agent-kit/classify.js

@@ -0,0 +1,113 @@
+/**
+ * Classify Agent Kit managed files against disk and recorded hashes.
+ * @fileoverview File-state machine for install/update
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const { FILE_STATE } = require('./constants');
+const { sha256, sha256File } = require('./checksums');
+const { extractSection, hasManagedSection } = require('./managed-section');
+const { buildClaudeSkillShim } = require('./claude-shim');
+const { renderHostMarkdown } = require('./render-host-markdown');
+const { ALL_HOSTS } = require('./hosts');
+const { applyPlaceholders } = require('./workspace-skeleton');
+
+/**
+ * @param {object} item
+ * @returns {string}
+ */
+function currentHash(item) {
+  if (!fs.existsSync(item.targetAbs)) {
+    return null;
+  }
+  if (item.mode === 'managed-section') {
+    const text = fs.readFileSync(item.targetAbs, 'utf8');
+    const section = extractSection(text);
+    return section === null ? sha256File(item.targetAbs) : sha256(section);
+  }
+  return sha256File(item.targetAbs);
+}
+
+/**
+ * @param {object} item
+ * @param {string|null} recorded
+ * @returns {string}
+ */
+function classifyPresentFile(item, recorded) {
+  const hash = currentHash(item);
+  item.currentHash = hash;
+  if (item.mode === 'managed-section' && !hasManagedSection(fs.readFileSync(item.targetAbs, 'utf8'))) {
+    return FILE_STATE.USER_FILE_NO_MANAGED_SECTION;
+  }
+  if (recorded && hash === recorded) {
+    return FILE_STATE.UNCHANGED_MANAGED;
+  }
+  if (recorded && hash !== recorded) {
+    return FILE_STATE.MODIFIED_MANAGED;
+  }
+  if (hash === item.sourceHash) {
+    return FILE_STATE.UNCHANGED_MANAGED;
+  }
+  return FILE_STATE.MODIFIED_MANAGED;
+}
+
+/**
+ * @param {object} item
+ * @param {string[]} [hosts]
+ * @returns {string}
+ */
+function materializeSource(item, hosts) {
+  const raw = fs.readFileSync(item.sourceAbs, 'utf8');
+  if (item.mode === 'claude-shim') {
+    return buildClaudeSkillShim(item.skillName, raw);
+  }
+  if (item.render === 'hosts') {
+    return renderHostMarkdown(raw, hosts);
+  }
+  if (item.mode === 'if-missing') {
+    return applyPlaceholders(raw, { workspaceName: item.workspaceName });
+  }
+  return raw;
+}
+
+/**
+ * @param {object} item
+ * @param {Map<string, string>} recordedByPath
+ * @param {string[]} hosts
+ * @returns {string}
+ */
+function classifyItem(item, recordedByPath, hosts) {
+  item.sourceText = materializeSource(item, hosts);
+  item.sourceHash = item.mode === 'managed-section' ? sha256(item.sourceText.trim()) : sha256(item.sourceText);
+  if (!fs.existsSync(item.targetAbs)) {
+    item.currentHash = null;
+    return FILE_STATE.MISSING;
+  }
+  if (item.mode === 'if-missing') {
+    item.currentHash = sha256File(item.targetAbs);
+    return FILE_STATE.PROJECT_OWNED;
+  }
+  return classifyPresentFile(item, recordedByPath.get(item.targetRel) || null);
+}
+
+/**
+ * @param {object[]} items
+ * @param {object|null} state
+ * @param {string[]} [hosts]
+ * @returns {object[]}
+ */
+function classifyItems(items, state, hosts) {
+  const recordedByPath = new Map();
+  const resolved = Array.isArray(hosts) && hosts.length ? hosts : ALL_HOSTS.slice();
+  for (const row of (state && state.managedFiles) || []) {
+    recordedByPath.set(row.path, row.sha256);
+  }
+  for (const item of items) {
+    item.fileState = classifyItem(item, recordedByPath, resolved);
+  }
+  return items;
+}
+
+module.exports = { classifyItems, classifyItem, currentHash };

package/lib/agent-kit/claude-shim.js

@@ -0,0 +1,61 @@
+/**
+ * Claude Code adapters: thin skill pointers, no duplicated skill bodies.
+ * @fileoverview Generate .claude/skills shims that load .agents/skills
+ */
+
+'use strict';
+
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * @param {string} skillMd
+ * @returns {string}
+ */
+function extractSkillDescription(skillMd) {
+  const match = String(skillMd || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) {
+    return '';
+  }
+  const parsed = yaml.load(match[1]);
+  return String((parsed && parsed.description) || '').trim();
+}
+
+/**
+ * @param {string} name
+ * @param {string} skillMd
+ * @returns {string}
+ */
+function buildClaudeSkillShim(name, skillMd) {
+  const description = extractSkillDescription(skillMd) || name;
+  const folded = description.replace(/\n/g, '\n  ');
+  return [
+    '---',
+    `name: ${name}`,
+    'description: >',
+    `  ${folded}`,
+    '---',
+    '',
+    `Load and follow \`.agents/skills/${name}/SKILL.md\` and its \`references/\`.`,
+    'That file is the skill body. Do not invent a parallel workflow.',
+    ''
+  ].join('\n');
+}
+
+/**
+ * @param {object} kit
+ * @param {string} repoRoot
+ * @returns {object[]}
+ */
+function listClaudeSkillShims(kit, repoRoot) {
+  return (kit.manifest.skills || []).map((name) => ({
+    skillName: name,
+    sourceAbs: path.join(kit.root, 'skills', name, 'SKILL.md'),
+    targetRel: `.claude/skills/${name}/SKILL.md`,
+    targetAbs: path.join(repoRoot, '.claude/skills', name, 'SKILL.md'),
+    mode: 'claude-shim',
+    optional: true
+  }));
+}
+
+module.exports = { extractSkillDescription, buildClaudeSkillShim, listClaudeSkillShims };

package/lib/agent-kit/constants.js

@@ -0,0 +1,55 @@
+/**
+ * Agent Kit constants.
+ * @fileoverview Shared markers, paths, and classification names
+ */
+
+'use strict';
+
+const BEGIN_MARKER = '<!-- aifabrix-agent-kit:begin -->';
+const END_MARKER = '<!-- aifabrix-agent-kit:end -->';
+const STATE_RELATIVE = '.aifabrix/agent-kit.yaml';
+const SECTION_ID = 'aifabrix-agent-kit';
+
+const FILE_STATE = {
+  MISSING: 'MISSING',
+  UNCHANGED_MANAGED: 'UNCHANGED_MANAGED',
+  USER_FILE_NO_MANAGED_SECTION: 'USER_FILE_NO_MANAGED_SECTION',
+  MODIFIED_MANAGED: 'MODIFIED_MANAGED',
+  OBSOLETE_UNCHANGED_MANAGED: 'OBSOLETE_UNCHANGED_MANAGED',
+  OBSOLETE_MODIFIED_MANAGED: 'OBSOLETE_MODIFIED_MANAGED',
+  PROJECT_OWNED: 'PROJECT_OWNED'
+};
+
+const KIT_STATE = {
+  CURRENT: 'CURRENT',
+  UPDATE_AVAILABLE: 'UPDATE_AVAILABLE',
+  CONFLICTS: 'CONFLICTS',
+  NOT_INSTALLED: 'NOT_INSTALLED'
+};
+
+const ACTION = {
+  CREATE: 'create',
+  REPLACE: 'replace',
+  APPEND_SECTION: 'append-section',
+  SKIP: 'skip',
+  CONFLICT: 'conflict',
+  DELETE: 'delete',
+  RETAIN: 'retain'
+};
+
+const V1_MARKERS = [
+  '.cursor/commands/cust-0-plan.md',
+  '.cursor/rules/cust-commands.mdc',
+  '.cursor/skills/aifabrix-integration-lifecycle/SKILL.md'
+];
+
+module.exports = {
+  BEGIN_MARKER,
+  END_MARKER,
+  STATE_RELATIVE,
+  SECTION_ID,
+  FILE_STATE,
+  KIT_STATE,
+  ACTION,
+  V1_MARKERS
+};

package/lib/agent-kit/file-list.js

@@ -0,0 +1,103 @@
+/**
+ * Enumerate managed Agent Kit source/target files.
+ * @fileoverview Walk kit trees from the package manifest
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { listClaudeSkillShims } = require('./claude-shim');
+
+/**
+ * @param {string} absDir
+ * @param {string} relPrefix
+ * @returns {{ rel: string, abs: string }[]}
+ */
+function listTreeFiles(absDir, relPrefix) {
+  if (!fs.existsSync(absDir)) {
+    return [];
+  }
+  const out = [];
+  const entries = fs.readdirSync(absDir, { withFileTypes: true });
+  for (const ent of entries) {
+    const rel = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+    const abs = path.join(absDir, ent.name);
+    if (ent.isDirectory()) {
+      out.push(...listTreeFiles(abs, rel));
+    } else {
+      out.push({ rel, abs });
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {object} spec
+ * @param {string} kitRoot
+ * @param {string} repoRoot
+ * @returns {object[]}
+ */
+function expandManagedSpec(spec, kitRoot, repoRoot) {
+  const mode = spec.mode || 'tree';
+  const sourceAbs = path.join(kitRoot, spec.source);
+  if (mode === 'managed-section' || mode === 'file' || mode === 'if-missing') {
+    return [
+      {
+        sourceAbs,
+        targetRel: spec.target,
+        targetAbs: path.join(repoRoot, spec.target),
+        mode,
+        optional: false,
+        render: spec.render,
+        workspaceName: path.basename(repoRoot)
+      }
+    ];
+  }
+  return listTreeFiles(sourceAbs, '').map((file) => ({
+    sourceAbs: file.abs,
+    targetRel: path.posix.join(spec.target.replace(/\\/g, '/'), file.rel),
+    targetAbs: path.join(repoRoot, spec.target, file.rel),
+    mode: 'tree',
+    optional: Boolean(spec.when)
+  }));
+}
+
+/**
+ * @param {object} spec
+ * @param {{ includeShims?: boolean, includeClaude?: boolean }} opts
+ * @returns {boolean}
+ */
+function shouldIncludeOptional(spec, opts) {
+  if (spec.when === 'host-claude') {
+    return Boolean(opts.includeClaude);
+  }
+  if (spec.when === 'v1-migration') {
+    return Boolean(opts.includeShims);
+  }
+  return false;
+}
+
+/**
+ * @param {object} kit
+ * @param {string} repoRoot
+ * @param {{ includeShims?: boolean, includeClaude?: boolean }} [opts]
+ * @returns {object[]}
+ */
+function listManagedTargets(kit, repoRoot, opts = {}) {
+  const items = [];
+  for (const spec of kit.manifest.managed || []) {
+    items.push(...expandManagedSpec(spec, kit.root, repoRoot));
+  }
+  for (const spec of kit.manifest.optional || []) {
+    if (shouldIncludeOptional(spec, opts)) {
+      items.push(...expandManagedSpec(spec, kit.root, repoRoot));
+    }
+  }
+  if (opts.includeClaude) {
+    items.push(...listClaudeSkillShims(kit, repoRoot));
+  }
+  return items;
+}
+
+module.exports = { listTreeFiles, listManagedTargets };

package/lib/agent-kit/host-approve.js

@@ -0,0 +1,130 @@
+/**
+ * Claude Code and Codex auto-approve configs for Agent Kit install.
+ * @fileoverview Project-local settings only — never ~/.claude or ~/.codex
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+
+const CLAUDE_REL = '.claude/settings.local.json';
+const CODEX_REL = '.codex/config.toml';
+const IGNORE_COMMENT = '# Host auto-approve (machine-local; aifabrix agent-kit)';
+const IGNORE_LINES = [CLAUDE_REL, CODEX_REL];
+
+/**
+ * This workspace for writes. Read(~/**) is home-anchored. Bash(aifabrix *)
+ * allows the delivery CLI without granting every shell command.
+ * @returns {object}
+ */
+function buildClaudeSettings() {
+  return {
+    permissions: {
+      defaultMode: 'bypassPermissions',
+      allow: ['Bash(aifabrix *)', 'Read(~/**)']
+    }
+  };
+}
+
+/**
+ * Auto-approve tools inside this workspace; do not disable the sandbox.
+ * @returns {string}
+ */
+function buildCodexConfig() {
+  return ['approval_policy = "never"', 'sandbox_mode = "workspace-write"', ''].join('\n');
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {object} fsApi
+ * @param {boolean} dryRun
+ * @returns {{ path: string, action: string }}
+ */
+function ensureGitignore(repoRoot, fsApi, dryRun) {
+  const rel = '.gitignore';
+  const abs = path.join(repoRoot, rel);
+  const existing = fsApi.existsSync(abs) ? fsApi.readFileSync(abs, 'utf8') : '';
+  const missing = IGNORE_LINES.filter((line) => !existing.split(/\r?\n/).includes(line));
+  if (!missing.length) {
+    return { path: rel, action: 'skip' };
+  }
+  if (dryRun) {
+    return { path: rel, action: 'planned' };
+  }
+  const prefix = existing && !existing.endsWith('\n') ? `${existing}\n` : existing;
+  const block = `${prefix}${existing ? '\n' : ''}${IGNORE_COMMENT}\n${missing.join('\n')}\n`;
+  fsApi.writeFileSync(abs, block, 'utf8');
+  return { path: rel, action: existing ? 'update' : 'create' };
+}
+
+/**
+ * @param {object} p
+ * @returns {{ path: string, action: string }}
+ */
+function writeHostFile(p) {
+  const { abs, rel, body, dryRun, force, fsApi } = p;
+  const exists = fsApi.existsSync(abs);
+  if (exists && !force) {
+    return { path: rel, action: 'exists' };
+  }
+  if (dryRun) {
+    return { path: rel, action: exists ? 'planned-replace' : 'planned' };
+  }
+  fsApi.mkdirSync(path.dirname(abs), { recursive: true });
+  fsApi.writeFileSync(abs, body, 'utf8');
+  return { path: rel, action: exists ? 'replace' : 'create' };
+}
+
+/**
+ * @param {object} options
+ * @returns {object[]}
+ */
+function listApproveWrites(options) {
+  const writes = [];
+  if (options.hosts.includes('claude')) {
+    const body = `${JSON.stringify(buildClaudeSettings(), null, 2)}\n`;
+    writes.push({ abs: path.join(options.repoRoot, CLAUDE_REL), rel: CLAUDE_REL, body });
+  }
+  if (options.hosts.includes('codex')) {
+    writes.push({
+      abs: path.join(options.repoRoot, CODEX_REL),
+      rel: CODEX_REL,
+      body: buildCodexConfig()
+    });
+  }
+  return writes;
+}
+
+/**
+ * @param {object} options
+ * @returns {{ requested: boolean, files: { path: string, action: string }[] }}
+ */
+function writeApproveAllFiles(options) {
+  if (!options.approveAll) {
+    return { requested: false, files: [] };
+  }
+  const fsApi = options.fs || fs;
+  const ctx = {
+    repoRoot: options.repoRoot,
+    hosts: options.hosts || [],
+    fsApi
+  };
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.force);
+  const files = listApproveWrites(ctx).map((row) =>
+    writeHostFile({ ...row, dryRun, force, fsApi })
+  );
+  if (files.length) {
+    files.push(ensureGitignore(options.repoRoot, fsApi, dryRun));
+  }
+  return { requested: true, files };
+}
+
+module.exports = {
+  CLAUDE_REL,
+  CODEX_REL,
+  buildClaudeSettings,
+  buildCodexConfig,
+  writeApproveAllFiles
+};

package/lib/agent-kit/hosting/github.js

@@ -0,0 +1,63 @@
+/**
+ * GitHub hosting adapter for agent-kit init / remote create.
+ * @fileoverview Uses gh CLI; injectable exec for tests
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+/**
+ * @param {{ execFileSync?: Function }} [options]
+ * @returns {{ authenticated: boolean }}
+ */
+function getGithubAuthStatus(options = {}) {
+  const exec = options.execFileSync || execFileSync;
+  try {
+    exec('gh', ['auth', 'status'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    return { authenticated: true };
+  } catch {
+    return { authenticated: false };
+  }
+}
+
+/**
+ * @param {object} params
+ * @param {string} params.name - repo name (basename)
+ * @param {string} [params.org]
+ * @param {string} [params.visibility]
+ * @param {string} params.cwd
+ * @param {boolean} [params.dryRun]
+ * @param {Function} [params.execFileSync]
+ * @returns {{ provider: string, fullName: string, visibility: string, pushed: boolean }}
+ */
+function createGithubRemote(params) {
+  const visibility = params.visibility === 'public' ? 'public' : 'private';
+  const fullName = params.org ? `${params.org}/${params.name}` : params.name;
+  const exec = params.execFileSync || execFileSync;
+  if (params.dryRun) {
+    return { provider: 'github', fullName, visibility, pushed: false };
+  }
+  const args = [
+    'repo',
+    'create',
+    fullName,
+    visibility === 'public' ? '--public' : '--private',
+    '--source',
+    '.',
+    '--remote',
+    'origin',
+    '--push'
+  ];
+  exec('gh', args, {
+    cwd: params.cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  return { provider: 'github', fullName, visibility, pushed: true };
+}
+
+module.exports = { getGithubAuthStatus, createGithubRemote };