vibecoding-devtools 1.0.1

package/installer/panel.mjs

@@ -0,0 +1,99 @@
+import { parseArgs } from 'node:util';
+import * as clack from '@clack/prompts';
+
+export const CLIS = ['claude', 'codex', 'agy'];
+export const STACKS = ['typescript', 'python', 'golang', 'rust', 'java', 'kotlin', 'php', 'ruby', 'swift', 'csharp', 'fsharp', 'dart', 'cpp', 'perl', 'arkts', 'react', 'react-native', 'vue', 'nuxt', 'angular'];
+const names = { claude: 'Claude Code', codex: 'Codex', agy: 'Antigravity' };
+const uniqueList = (value, allowed, name) => {
+  const items = value === '' || value === 'none' ? [] : value.split(',').map((s) => s.trim());
+  if (items.some((s) => !allowed.includes(s))) throw new Error(`Invalid ${name}: ${value}`);
+  return [...new Set(items)];
+};
+
+export function parseFlags(args = []) {
+  const booleans = ['dry-run', 'yes', 'force', 'json', 'maestri', 'no-maestri', 'hooks', 'no-hooks', 'ecc-hooks', 'no-ecc-hooks', 'impeccable-hooks', 'no-impeccable-hooks', 'project', 'help'];
+  const strings = ['clis', 'cli', 'scope', 'ecc', 'ecc-clis', 'ecc-stacks', 'stacks', 'impeccable', 'impeccable-clis'];
+  const options = Object.fromEntries([...booleans.map((k) => [k, { type: 'boolean' }]), ...strings.map((k) => [k, { type: 'string' }])]);
+  const { values, positionals } = parseArgs({ args, options, allowPositionals: true, strict: true });
+  if (positionals.length > 1) throw new Error('Specify only one command');
+  const command = positionals[0] ?? 'install';
+  if (!['install', 'update', 'detect', 'uninstall'].includes(command)) throw new Error(`Unknown command: ${command}`);
+  for (const [a, b] of [['clis', 'cli'], ['ecc', 'ecc-clis'], ['ecc-stacks', 'stacks'], ['impeccable', 'impeccable-clis']]) {
+    if (values[a] !== undefined && values[b] !== undefined) throw new Error(`Use only --${a} or --${b}`);
+  }
+  if (values.project && values.scope && values.scope !== 'project') throw new Error('--project conflicts with --scope');
+  for (const name of ['maestri', 'hooks', 'ecc-hooks', 'impeccable-hooks']) {
+    if (values[name] && values[`no-${name}`]) throw new Error(`Use only --${name} or --no-${name}`);
+  }
+  return { command, ...values,
+    hasChoices: [...strings, 'project', 'maestri', 'no-maestri', 'hooks', 'no-hooks', 'ecc-hooks', 'no-ecc-hooks', 'impeccable-hooks', 'no-impeccable-hooks'].some((k) => values[k] !== undefined) };
+}
+
+export function choicesFromFlags(flags, detection, saved) {
+  if (saved) {
+    // Normalize aliases before merging, so an explicit alias wins over saved choices.
+    const scope = flags.project ? 'project' : flags.scope ?? saved.scope;
+    const ecc = flags.ecc ?? flags['ecc-clis'] ?? saved.ecc.clis.join(',');
+    const impeccable = flags.impeccable ?? flags['impeccable-clis'] ?? saved.impeccable.clis.join(',');
+    flags = { ...flags, scope, clis: flags.clis ?? flags.cli ?? saved.clis.join(','), ecc, impeccable,
+      maestri: flags.maestri ?? saved.maestri, hooks: flags.hooks ?? saved.hooks,
+      'ecc-hooks': flags['ecc-hooks'] ?? (ecc && ecc !== 'none' ? saved.ecc.hooks : false),
+      'impeccable-hooks': flags['impeccable-hooks'] ?? (impeccable && impeccable !== 'none' ? saved.impeccable.hooks : false),
+      'ecc-stacks': flags['ecc-stacks'] ?? flags.stacks ?? (scope === 'project' && ecc && ecc !== 'none' ? saved.ecc.stacks.join(',') : '') };
+  }
+  flags = { ...flags };
+  for (const name of ['maestri', 'hooks', 'ecc-hooks', 'impeccable-hooks']) {
+    if (flags[`no-${name}`]) flags[name] = false;
+  }
+  const clis = flags.clis ?? flags.cli;
+  const targets = clis === undefined ? (detection.clis ?? []).filter((c) => ['ok', 'off-path'].includes(c.state)).map((c) => c.id) : uniqueList(clis, CLIS, 'CLI');
+  const scope = flags.project ? 'project' : flags.scope ?? 'global';
+  if (!['global', 'project'].includes(scope)) throw new Error('Scope must be global or project');
+  if (scope === 'project' && (!detection.project?.inRepository || !detection.project.root)) throw new Error('Project scope requires a git repository');
+  const eccClis = uniqueList(flags.ecc ?? flags['ecc-clis'] ?? '', ['claude', 'codex'], 'ECC CLI');
+  const impeccableClis = uniqueList(flags.impeccable ?? flags['impeccable-clis'] ?? '', CLIS, 'Impeccable CLI');
+  const stacksFlag = flags['ecc-stacks'] ?? flags.stacks;
+  const stacks = stacksFlag === undefined ? (scope === 'project' && eccClis.length ? detection.project.stacks ?? [] : []) : uniqueList(stacksFlag, STACKS, 'ECC package');
+  if (flags['ecc-hooks'] && !eccClis.length) throw new Error('--ecc-hooks requires --ecc with CLIs');
+  if (flags['impeccable-hooks'] && !impeccableClis.length) throw new Error('--impeccable-hooks requires --impeccable with CLIs');
+  if (stacks.length && (!eccClis.length || scope !== 'project')) throw new Error('Stack packages require ECC and project scope');
+  return { clis: targets, scope, ...(scope === 'project' ? { root: detection.project.root } : {}), maestri: flags.maestri ?? false,
+    hooks: flags['no-hooks'] ? false : flags.hooks ?? true,
+    ecc: { clis: eccClis, hooks: flags['ecc-hooks'] ?? false, stacks: [...stacks] }, impeccable: { clis: impeccableClis, hooks: flags['impeccable-hooks'] ?? false } };
+}
+
+export class Cancellation extends Error {
+  constructor() { super('Operation cancelled'); this.name = 'Cancellation'; }
+}
+
+export async function confirmExecution({ prompts = clack } = {}) {
+  const answer = await prompts.confirm({ message: 'Apply the summary actions?', initialValue: false });
+  if (prompts.isCancel(answer)) throw new Cancellation();
+  return answer;
+}
+
+export async function panel(detection, { prompts = clack } = {}) {
+  const ask = async (type, options) => {
+    const answer = await prompts[type](options);
+    if (prompts.isCancel(answer)) throw new Cancellation();
+    return answer;
+  };
+  const cliOptions = CLIS.map((value) => ({ value, label: names[value], hint: detection.clis?.find((c) => c.id === value)?.state ?? 'missing' }));
+  const defaults = choicesFromFlags({}, detection);
+  const clis = await ask('multiselect', { message: 'Target CLIs for the kit', options: cliOptions, initialValues: defaults.clis, required: false });
+  const scope = await ask('select', { message: 'Installation scope', initialValue: 'global', options: [
+    { value: 'global', label: 'Global' }, ...(detection.project?.inRepository ? [{ value: 'project', label: `Project: ${detection.project.root}` }] : []),
+  ] });
+  const maestri = await ask('confirm', { message: 'Include the Maestri pack?', initialValue: false });
+  const kitHooks = await ask('confirm', { message: 'Install kit hooks?', initialValue: true });
+  const eccClis = await ask('multiselect', { message: 'Which CLIs should receive ECC?', options: cliOptions.filter(({ value }) => value !== 'agy'), initialValues: [], required: false });
+  let hooks = false;
+  let stacks = [];
+  if (eccClis.length) {
+    hooks = await ask('confirm', { message: 'Enable ECC hooks?', initialValue: false });
+    if (scope === 'project') stacks = await ask('multiselect', { message: 'ECC stack rule packages', options: STACKS.map((value) => ({ value, label: value })), initialValues: (detection.project.stacks ?? []).filter((s) => STACKS.includes(s)), required: false });
+  }
+  const impeccableClis = await ask('multiselect', { message: 'Which CLIs should receive Impeccable?', options: cliOptions, initialValues: [], required: false });
+  const impeccableHooks = impeccableClis.length ? await ask('confirm', { message: 'Enable Impeccable hooks?', initialValue: false }) : false;
+  return choicesFromFlags({ clis: clis.join(','), scope, maestri, hooks: kitHooks, ecc: eccClis.join(','), 'ecc-hooks': hooks, 'ecc-stacks': stacks.join(','), impeccable: impeccableClis.join(','), 'impeccable-hooks': impeccableHooks }, detection);
+}

package/installer/plan.mjs

@@ -0,0 +1,255 @@
+// Read-only planning performs no writes, network calls, execution or real-home access.
+import fs from "node:fs";
+import path from "node:path";
+import { isUtf8 } from "node:buffer";
+import { readState, hashContent } from "./state.mjs";
+import { convertAntigravityRule, readFrontmatter, buildCodexBlock } from "./convert.mjs";
+import { hookActions } from './hooks.mjs';
+import { jsonMergeSituation } from './json-merge.mjs';
+
+const CLIS = ["claude", "codex", "agy"];
+const uniqueList = (items = []) => [...new Set(items)].sort();
+const entries = (directory) => fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) =>
+  a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+const readRules = (directory) => entries(directory).filter((e) => e.isFile() && e.name.endsWith(".md"))
+  .map((e) => ({ name: e.name, source: path.join(directory, e.name),
+    content: fs.readFileSync(path.join(directory, e.name), "utf8") }));
+
+const START = "<!-- vibecoding-devtools:start -->";
+const END = "<!-- vibecoding-devtools:end -->";
+const stat = (file) => {
+  try { return fs.lstatSync(file); }
+  catch (error) { if (["ENOENT", "ENOTDIR"].includes(error.code)) return null; throw error; }
+};
+const samePath = (a, b) => typeof a === "string" && path.resolve(a) === path.resolve(b);
+
+function extractBlock(text) {
+  const start = text.indexOf(START);
+  const end = text.indexOf(END);
+  if (start < 0 && end < 0) return null;
+  if (start < 0 || end < start || text.indexOf(START, start + START.length) >= 0
+    || text.indexOf(END, end + END.length) >= 0) return { invalid: true };
+  return { content: text.slice(start, end + END.length), start, end: end + END.length };
+}
+
+// Measure complete resulting files including markers, separators and preserved external content.
+function codexBytes(actions, home, project, items) {
+  const files = new Set([path.join(home, ".codex", "AGENTS.md")]);
+  if (project) files.add(path.join(project, "AGENTS.md"));
+  let bytes = 0;
+  for (const file of files) {
+    const copied = actions.find((a) => a.type === "copy" && samePath(a.destination, file));
+    let text = stat(file) ? fs.readFileSync(file, "utf8") : "";
+    if (copied && ["new", "update"].includes(situationOf(copied, items))) {
+      const previous = extractBlock(text);
+      const record = items.find((i) => i.type === "block" && samePath(i.destination, file));
+      text = fs.readFileSync(copied.source, "utf8");
+      if (previous && !previous.invalid && record && hashContent(previous.content) === record.hash) {
+        text += (record.separator ?? "") + previous.content;
+      }
+    }
+    const action = actions.find((a) => a.type === "block" && samePath(a.destination, file));
+    if (action) {
+      const block = extractBlock(text);
+      const replacement = `${START}\n${action.content}\n${END}`;
+      text = block && !block.invalid ? text.slice(0, block.start) + replacement + text.slice(block.end)
+        : text + (text && !text.endsWith("\n") ? "\n" : "") + replacement;
+    }
+    bytes += Buffer.byteLength(text);
+  }
+  return bytes;
+}
+
+function situationOf(action, items) {
+  // Destination links and linked ancestors are conflicts and never escape the target tree.
+  for (let p = path.resolve(action.destination); ; p = path.dirname(p)) {
+    const ancestor = stat(p);
+    if (ancestor?.isSymbolicLink()
+      || (p !== path.resolve(action.destination) && ancestor && !ancestor.isDirectory())) return "conflict";
+    if (p === path.dirname(p)) break;
+  }
+  const st = stat(action.destination);
+  if (!st) return "new";
+  if (action.type === "copy" && fs.lstatSync(action.source).isDirectory()) {
+    if (!st.isDirectory()) return "conflict";
+    const names = entries(action.source).map((e) => e.name);
+    // Extra content survives copying, so the complete directory cannot be classified as identical.
+    if (entries(action.destination).some((e) => !names.includes(e.name))) return "conflict";
+    const situations = names.map((name) => situationOf({ ...action,
+      source: path.join(action.source, name), destination: path.join(action.destination, name) }, items));
+    return ["conflict", "update", "new"].find((s) => situations.includes(s)) ?? "same";
+  }
+  if (!st.isFile()) return "conflict";
+  const current = fs.readFileSync(action.destination);
+  let previous = items.find((item) => item.type === action.type && samePath(item.destination, action.destination));
+  if (previous?.pending && previous.hashBefore === hashContent(current)) previous = previous.previous;
+  if (action.type === 'json-merge') return jsonMergeSituation(current, action, previous);
+  if (action.type === "block") {
+    if (!isUtf8(current)) return "conflict";
+    const block = extractBlock(current.toString("utf8"));
+    if (!block) return "new"; // Adding a block preserves external AGENTS.md content.
+    if (block.invalid) return "conflict";
+    const replacement = `${START}\n${action.content}\n${END}`;
+    if (block.content === replacement) return "same";
+    return previous?.type === "block" && previous.hash === hashContent(block.content)
+      ? "update" : "conflict";
+  }
+  const expected = action.type === "copy" ? fs.readFileSync(action.source) : Buffer.from(action.content);
+  if (current.equals(expected)) return "same";
+  // Project templates may already contain a Codex block from the initial installation.
+  let base = current;
+  if (action.description === "Project template AGENTS.md") {
+    const text = current.toString("utf8");
+    const block = extractBlock(text);
+    if (block && !block.invalid) {
+      const record = items.find((i) => i.type === "block" && samePath(i.destination, action.destination));
+      let start = block.start;
+      if (record?.separator && text.slice(start - record.separator.length, start) === record.separator) {
+        start -= record.separator.length;
+      }
+      const withoutBlock = Buffer.from(text.slice(0, start) + text.slice(block.end));
+      if (withoutBlock.equals(expected)) return "same";
+      if (record && hashContent(block.content) === record.hash) base = withoutBlock;
+    }
+  }
+  return previous && !previous.pending && previous.hash === hashContent(base)
+    ? "update" : "conflict";
+}
+
+// Directory copies are recorded per file. Compare their current source tree, not
+// just the directory destination, so removed children also leave the installation.
+export function reconcileUpdate(plan, { home }) {
+  const state = readState({ home });
+  const actions = [];
+  const expand = (action) => {
+    if (action.owner === 'kit' && action.type === 'copy' && fs.lstatSync(action.source).isDirectory()) {
+      const children = entries(action.source);
+      if (!children.length) actions.push({ ...action, situation: situationOf(action, state.items) });
+      for (const child of children) expand({ ...action, source: path.join(action.source, child.name),
+        destination: path.join(action.destination, child.name) });
+    } else actions.push(action.owner === 'kit' && action.destination
+      ? { ...action, situation: situationOf(action, state.items) } : action);
+  };
+  for (const action of plan) expand(action);
+  const key = (item) => JSON.stringify([item.type, path.resolve(item.destination),
+    item.type === 'block' ? item.marker ?? START : null]);
+  const wanted = new Set(actions.filter((a) => a.destination).map(key));
+  const removals = state.items.filter((item) => item.owner === 'kit'
+    && ['copy', 'write', 'block', 'json-merge'].includes(item.type) && !wanted.has(key(item)))
+    .map((item) => ({ ...item, operation: 'remove', situation: 'remove' }));
+  return Object.assign([...removals, ...actions], { warnings: plan.warnings, preparation: plan.preparation });
+}
+
+export function buildPlan(choices, detection, paths) {
+  const { home, kit, ecc, project } = paths;
+  if (!home || !kit) throw new Error("paths.home and paths.kit are required");
+  const state = detection?.installed?.state ?? readState({ home });
+  if (!["global", "project"].includes(choices.scope)) throw new Error("Invalid scope");
+  const local = choices.scope === "project";
+  if (local && !project) throw new Error("Project scope requires paths.project");
+  const kitClis = uniqueList(choices.clis);
+  const eccClis = uniqueList(choices.ecc?.clis);
+  if (eccClis.includes("agy")) throw new Error("ECC is not supported on Antigravity");
+  const clis = uniqueList([...kitClis, ...eccClis]);
+  if (clis.some((cli) => !CLIS.includes(cli))) throw new Error("Invalid CLI");
+  if (eccClis.length && !ecc) throw new Error("Selected ECC requires downloaded paths.ecc");
+  const root = local ? project : home;
+  const actions = [];
+  const warnings = [];
+  const destinations = new Map();
+  const add = (type, owner, cli, source, destination, content, description) => {
+    const action = { type, owner, cli, source, destination, content, description };
+    const key = `${type}:${destination.toLowerCase()}`;
+    if (destinations.has(key)) {
+      const previous = destinations.get(key);
+      if (previous.source !== source || previous.content !== content) {
+        throw new Error(`Destination collision: ${destination}`);
+      }
+      return;
+    }
+    destinations.set(key, action);
+    actions.push(action);
+  };
+  if (local && clis.length) {
+    for (const name of ["AGENTS.md", ...(clis.includes("claude") ? ["CLAUDE.md"] : [])]) {
+      add("copy", "kit", name === "CLAUDE.md" ? "claude" : clis.includes("codex") ? "codex" : clis[0],
+        path.join(kit, "templates", name), path.join(project, name), null, `Project template ${name}`);
+    }
+  }
+  for (const cli of clis) {
+    const destinationRules = cli === "claude" ? path.join(root, ".claude", "rules")
+      : local ? path.join(project, ".agents", "rules") : path.join(home, ".gemini", "config", "rules");
+    const codexBase = path.join(root, ".codex", "vibecoding");
+    const codexRules = [];
+    if (kitClis.includes(cli)) {
+      const rules = readRules(path.join(kit, "rules")).filter((r) => choices.maestri || !r.name.startsWith("maestri-"));
+      for (const rule of rules) {
+        if (cli === "claude") {
+          add("copy", "kit", cli, rule.source, path.join(destinationRules, "vibecoding", rule.name),
+            null, `Kit rule: ${rule.name}`);
+        } else if (cli === "agy") {
+          add("write", "kit", cli, rule.source, path.join(destinationRules, `vibecoding-${rule.name}`),
+            convertAntigravityRule(rule.content), `Converted rule: ${rule.name}`);
+        } else {
+          const destination = path.join(codexBase, "rules", rule.name);
+          if (readFrontmatter(rule.content).paths.length) {
+            add("copy", "kit", cli, rule.source, destination, null, `On-demand rule: ${rule.name}`);
+          }
+          codexRules.push({ ...rule, destination });
+        }
+      }
+      const destinationSkills = cli === "claude" ? path.join(root, ".claude", "skills")
+        : cli === "codex" || local ? path.join(root, ".agents", "skills")
+          : path.join(home, ".gemini", "config", "skills");
+      for (const skill of entries(path.join(kit, "skills"))) {
+        if (!skill.isDirectory() || (!choices.maestri && skill.name.startsWith("maestri-"))) continue;
+        add("copy", "kit", cli, path.join(kit, "skills", skill.name),
+          path.join(destinationSkills, skill.name), null, `Kit skill: ${skill.name}`);
+      }
+    }
+    if (eccClis.includes(cli)) {
+      const packages = uniqueList(["common", ...(cli === "claude" ? ["web"] : []),
+        ...(local ? choices.ecc?.stacks ?? [] : [])]);
+      const packageFiles = Object.fromEntries(packages.map((packageName) => {
+        if (!/^[a-z0-9-]+$/i.test(packageName)) throw new Error(`Invalid ECC package: ${packageName}`);
+        return [packageName, readRules(path.join(ecc, "rules", packageName))];
+      }));
+      for (const packageName of packages) {
+        const directory = path.join(ecc, "rules", packageName);
+        const rules = packageFiles[packageName];
+        if (cli === "claude") {
+          add("copy", "ecc", cli, directory, path.join(destinationRules, "ecc", packageName),
+            null, `ECC rules: ${packageName}`);
+        } else {
+          // Preserve directories so original relative links to common rules keep working.
+          add("copy", "ecc", cli, directory, path.join(codexBase, "ecc", packageName), null, `ECC rules: ${packageName}`);
+          for (const rule of rules) codexRules.push({ ...rule, owner: "ecc",
+            packageName, destinationDirectory: path.join(codexBase, "ecc", packageName),
+            destination: path.join(codexBase, "ecc", packageName, rule.name),
+            when: packageName === "common" ? `code (${packageName}/${rule.name})` : `the stack ${packageName} (${rule.name})` });
+        }
+      }
+    }
+    if (cli === "codex" && codexRules.length) {
+      add("block", kitClis.includes(cli) ? "kit" : "ecc", cli, null,
+        local ? path.join(project, "AGENTS.md") : path.join(home, ".codex", "AGENTS.md"),
+        buildCodexBlock(codexRules), "Codex rules and routing");
+      const original = codexBytes(actions, home, project, state.items);
+      if (original > 32 * 1024) {
+        const action = actions.at(-1);
+        action.content = buildCodexBlock(codexRules, { byPackage: true });
+        const reduced = codexBytes(actions, home, project, state.items);
+        const warning = `Codex: estimated context of ${original} bytes exceeds 32 KiB; `
+          + `routing reduced to one line per package (${reduced} bytes).`;
+        if (reduced > 32 * 1024) {
+          throw new Error(`${warning} Still exceeds the 32768-byte limit; reduce AGENTS.md files before installing.`);
+        }
+        warnings.push(warning);
+      }
+    }
+  }
+  actions.push(...hookActions(choices, { home, kit, project }));
+  const plan = actions.map((action) => ({ ...action, situation: situationOf(action, state.items) }));
+  if (warnings.length) plan.warnings = warnings;
+  return plan;
+}

package/installer/state.mjs

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const kitVersion = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+export const hashContent = (content) => createHash('sha256').update(content).digest('hex');
+export const statePath = (home = os.homedir()) => path.join(home, '.vibecoding-devtools', 'state.json');
+
+export function readState({ home = os.homedir() } = {}) {
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath(home), 'utf8'));
+    if (!state || !Array.isArray(state.items) || typeof state.version !== 'string') {
+      throw new Error('Invalid installer state');
+    }
+    return state;
+  } catch (error) {
+    if (error.code === 'ENOENT') return { version: kitVersion, date: null, items: [] };
+    throw error; // Corrupt state never becomes an empty installation.
+  }
+}
+
+export function writeAtomic(destination, content) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  const temporary = `${destination}.${randomUUID()}.tmp`;
+  let fd;
+  try {
+    let mode = 0o600;
+    try { mode = fs.statSync(destination).mode & 0o777; } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    fd = fs.openSync(temporary, 'wx', mode);
+    fs.writeFileSync(fd, content);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(temporary, destination);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+export function saveState(state, { home = os.homedir() } = {}) {
+  const content = JSON.stringify({ ...state, version: kitVersion, date: new Date().toISOString() }, null, 2) + '\n';
+  writeAtomic(statePath(home), content);
+}
+
+export const lockPath = (home) => path.join(home, '.vibecoding-devtools', 'installer.lock');
+
+// The lock covers the whole read, effect and write transaction, including JSON replacement.
+// Live PIDs never expire; incomplete locks can be recovered only after 30 seconds.
+export function withLock(home, work, { dryRun = false } = {}) {
+  if (dryRun) return work(); // Dry-run creates and removes no files.
+  const file = lockPath(home);
+  for (let p = path.dirname(file); ; p = path.dirname(p)) {
+    try { if (fs.lstatSync(p).isSymbolicLink()) throw new Error(`Link in state directory: ${p}`); }
+    catch (e) { if (e.code !== 'ENOENT') throw e; }
+    if (p === path.dirname(p)) break;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const token = randomUUID();
+  let fd;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      fd = fs.openSync(file, 'wx', 0o600);
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const st = fs.lstatSync(file);
+      if (!st.isFile() || st.isSymbolicLink()) throw new Error('Invalid installer lock');
+      const text = fs.readFileSync(file, 'utf8');
+      let stale = false;
+      try {
+        const lock = JSON.parse(text);
+        if (!Number.isInteger(lock.pid) || lock.pid <= 0 || typeof lock.token !== 'string') throw new Error();
+        try { process.kill(lock.pid, 0); }
+        catch (e) { if (e.code === 'ESRCH') stale = true; }
+      } catch {
+        stale = Date.now() - st.mtimeMs > 30000;
+      }
+      if (!stale) throw new Error('Another installation is in progress (active lock)');
+      if (fs.readFileSync(file, 'utf8') !== text) continue;
+      fs.unlinkSync(file);
+    }
+  }
+  if (fd === undefined) throw new Error('Could not acquire the installer lock');
+  const acquired = fs.fstatSync(fd);
+  try {
+    fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, token }));
+    fs.fsyncSync(fd);
+    return work();
+  } finally {
+    fs.closeSync(fd);
+    // Never release a lock now owned by another process.
+    try {
+      const current = fs.lstatSync(file);
+      if (current.dev === acquired.dev && current.ino === acquired.ino) {
+        let mine = true;
+        try { mine = JSON.parse(fs.readFileSync(file, 'utf8')).token === token; }
+        catch (e) { if (!(e instanceof SyntaxError)) throw e; } // The initial lock write failed.
+        if (mine) fs.unlinkSync(file);
+      }
+    }
+    catch (e) { if (e.code !== 'ENOENT') throw e; }
+  }
+}

package/installer/third-party.json

@@ -0,0 +1,16 @@
+{
+  "ecc": {
+    "packageName": "ecc-universal",
+    "version": "2.2.3",
+    "repository": "https://github.com/affaan-m/ECC.git",
+    "tag": "v2.2.3",
+    "marketplace": "affaan-m/ECC@v2.2.3",
+    "plugin": "ecc@ecc",
+    "modules": ["agents-core", "commands-core", "platform-configs", "workflow-quality"],
+    "hooksModule": "hooks-runtime"
+  },
+  "impeccable": {
+    "packageName": "impeccable",
+    "version": "4.8.0"
+  }
+}