@ai-content-space/loopx 0.1.0

package/src/cli.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+import { autopilotStage, approveStage, buildStage, clarifyStage, initWorkspace, planStage, reviewStage, statusSummary } from './workflow.mjs';
+import { installBundledSkills } from './install-discovery.mjs';
+import { doctorRuntime, migrateLegacyRuntime } from './runtime-maintenance.mjs';
+
+function usage() {
+  return [
+    'Usage:',
+    '  loopx init [--slug <slug>]',
+    '  loopx clarify <slug>',
+    '  loopx approve <slug> --from <stage> --to <stage>',
+    '  loopx plan <slug>',
+    '  loopx build <slug>',
+    '  loopx review <slug> [--reviewer <name>]',
+    '  loopx autopilot <slug> [--reviewer <name>]',
+    '  loopx status [slug] [--json]',
+    '  loopx doctor',
+    '  loopx migrate',
+    '  loopx repair-install',
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const positionals = [];
+  const options = new Map();
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index];
+    if (!token.startsWith('--')) {
+      positionals.push(token);
+      continue;
+    }
+    const next = rest[index + 1];
+    if (!next || next.startsWith('--')) {
+      options.set(token, true);
+      continue;
+    }
+    options.set(token, next);
+    index += 1;
+  }
+
+  return { command, positionals, options };
+}
+
+function printHumanStatus(status) {
+  if (!status.initialized) {
+    console.log('LoopX workspace is not initialized.');
+    console.log(status.next_action);
+    return;
+  }
+  if (!status.slug) {
+    console.log(`workspace: ${status.workspaceRoot}`);
+    console.log(`workflows: ${status.workflow_count}`);
+    console.log(`legacy: ${status.summary.legacy}`);
+    for (const workflow of status.workflows) {
+      console.log(`- ${workflow.slug}: stage=${workflow.current_stage ?? '(none)'} contract=${workflow.contract}`);
+    }
+    console.log(`next: ${status.next_action}`);
+    return;
+  }
+
+  console.log(`workflow: ${status.slug}`);
+  console.log(`contract: ${status.contract}`);
+  console.log(`schema_version: ${status.schema_version}`);
+  console.log(`stage: ${status.state?.current_stage ?? '(none)'}`);
+  console.log(`requested_transition: ${status.state?.requested_transition ?? 'none'}`);
+  console.log(`last_confirmed_transition: ${status.state?.last_confirmed_transition ?? 'none'}`);
+  console.log(`pending_user_decision: ${status.state?.pending_user_decision ?? 'none'}`);
+  console.log(`missing artifacts: ${status.missing_artifacts.length > 0 ? status.missing_artifacts.join(', ') : '(none)'}`);
+  console.log(`next: ${status.next_action}`);
+}
+
+async function main() {
+  const { command, positionals, options } = parseArgs(process.argv.slice(2));
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    console.log(usage());
+    return;
+  }
+
+  try {
+    switch (command) {
+      case 'init': {
+        const result = await initWorkspace(process.cwd(), { slug: options.get('--slug') || positionals[0] });
+        console.log(JSON.stringify({ ok: true, command, workspaceRoot: result.workspaceRoot, workflow: result.workflow?.state ?? null }, null, 2));
+        return;
+      }
+      case 'clarify': {
+        const result = await clarifyStage(process.cwd(), positionals[0]);
+        console.log(JSON.stringify({ ok: true, command, root: result.root, state: result.state }, null, 2));
+        return;
+      }
+      case 'approve': {
+        const result = await approveStage(process.cwd(), positionals[0], {
+          from: options.get('--from'),
+          to: options.get('--to'),
+        });
+        console.log(JSON.stringify({ ok: true, command, root: result.root, state: result.state }, null, 2));
+        return;
+      }
+      case 'plan': {
+        const result = await planStage(process.cwd(), positionals[0]);
+        console.log(JSON.stringify({ ok: true, command, root: result.root, state: result.state }, null, 2));
+        return;
+      }
+      case 'build': {
+        const result = await buildStage(process.cwd(), positionals[0]);
+        console.log(JSON.stringify({ ok: true, command, root: result.root, state: result.state }, null, 2));
+        return;
+      }
+      case 'review': {
+        const result = await reviewStage(process.cwd(), positionals[0], {
+          reviewer: options.get('--reviewer') || 'independent-reviewer',
+        });
+        console.log(JSON.stringify({ ok: true, command, root: result.root, state: result.state, verdict: result.verdict }, null, 2));
+        return;
+      }
+      case 'autopilot': {
+        const result = await autopilotStage(process.cwd(), positionals[0], {
+          reviewer: options.get('--reviewer') || 'autopilot-reviewer',
+        });
+        console.log(JSON.stringify({ ok: true, command, root: result.root, state: result.state, runPath: result.runPath }, null, 2));
+        return;
+      }
+      case 'status': {
+        const result = await statusSummary(process.cwd(), positionals[0]);
+        if (options.get('--json')) {
+          console.log(JSON.stringify({ ok: true, command, ...result }, null, 2));
+        } else {
+          printHumanStatus(result);
+        }
+        return;
+      }
+      case 'doctor': {
+        const result = await doctorRuntime(process.cwd(), process.env);
+        console.log(JSON.stringify({ ok: !result.mixedRuntimeRoots && result.installCheck.ok, command, ...result }, null, 2));
+        return;
+      }
+      case 'migrate': {
+        const result = await migrateLegacyRuntime(process.cwd());
+        console.log(JSON.stringify({ ok: true, command, ...result }, null, 2));
+        return;
+      }
+      case 'repair-install': {
+        const result = await installBundledSkills(process.env);
+        const ok = result.ok !== false;
+        console.log(JSON.stringify({ ok, command, ...result }, null, 2));
+        if (!ok) {
+          process.exitCode = 1;
+        }
+        return;
+      }
+      default:
+        throw new Error(`unknown_command:${command}`);
+    }
+  } catch (error) {
+    console.error(JSON.stringify({
+      ok: false,
+      command,
+      error: error instanceof Error ? error.message : String(error),
+    }, null, 2));
+    process.exitCode = 1;
+  }
+}
+
+await main();

package/src/install-discovery.mjs

@@ -0,0 +1,367 @@
+import { cp, lstat, mkdir, readFile, readdir, readlink, rm, symlink, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(MODULE_DIR, '..');
+const LOOPX_SKILLS = [
+  'loopx-clarify',
+  'loopx-plan',
+  'loopx-build',
+  'loopx-review',
+  'loopx-autopilot',
+];
+const LOOPX_INSTALLATION_IDENTITY = 'loopx';
+
+function jsonClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function isoNow() {
+  return new Date().toISOString();
+}
+
+export function getProjectRoot(env = process.env) {
+  return resolve(env.LOOPX_PROJECT_ROOT || PROJECT_ROOT);
+}
+
+export function getAgentsRoot(env = process.env) {
+  const home = resolve(env.LOOPX_HOME || env.HOME || process.cwd());
+  return resolve(env.LOOPX_AGENTS_ROOT || join(home, '.agents'));
+}
+
+export function getInstalledSkillsRoot(env = process.env) {
+  return resolve(env.LOOPX_SKILLS_ROOT || join(getAgentsRoot(env), 'skills'));
+}
+
+export function getSkillLockPath(env = process.env) {
+  return resolve(env.LOOPX_SKILL_LOCK_PATH || join(getAgentsRoot(env), '.skill-lock.json'));
+}
+
+export function getSkillSourceRoot(env = process.env) {
+  return resolve(env.LOOPX_SKILL_SOURCE_ROOT || join(getProjectRoot(env), 'skills'));
+}
+
+function getInstallOptions(options = {}, env = process.env) {
+  return {
+    installationIdentity: options.installationIdentity || env.LOOPX_INSTALLATION_IDENTITY || LOOPX_INSTALLATION_IDENTITY,
+    distributionChannel: options.distributionChannel || env.LOOPX_DISTRIBUTION_CHANNEL || 'npm',
+    sourceUrl: resolve(options.sourceUrl || env.LOOPX_SOURCE_URL || getProjectRoot(env)),
+    skillSourceRoot: resolve(options.skillSourceRoot || getSkillSourceRoot(env)),
+  };
+}
+
+function skillSourceDir(skillName, env = process.env, skillSourceRoot = getSkillSourceRoot(env)) {
+  return join(skillSourceRoot, skillName);
+}
+
+function skillSourceEntry(skillName, env = process.env, skillSourceRoot = getSkillSourceRoot(env)) {
+  return join(skillSourceDir(skillName, env, skillSourceRoot), 'SKILL.md');
+}
+
+function installedSkillDir(skillName, env = process.env) {
+  return join(getInstalledSkillsRoot(env), skillName);
+}
+
+async function fileHash(path) {
+  const hash = createHash('sha1');
+  const stat = await lstat(path);
+  if (stat.isDirectory()) {
+    const entries = (await readdir(path)).sort();
+    hash.update(path);
+    for (const entry of entries) {
+      hash.update(await fileHash(join(path, entry)));
+    }
+    return hash.digest('hex');
+  }
+
+  hash.update(await readFile(path));
+  return hash.digest('hex');
+}
+
+async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+
+async function readSkillLock(env = process.env) {
+  const path = getSkillLockPath(env);
+  if (!existsSync(path)) {
+    return {
+      path,
+      data: {
+        version: 3,
+        skills: {},
+      },
+    };
+  }
+
+  return {
+    path,
+    data: JSON.parse(await readFile(path, 'utf8')),
+  };
+}
+
+async function writeSkillLock(data, env = process.env) {
+  const path = getSkillLockPath(env);
+  await ensureDir(dirname(path));
+  await writeFile(path, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+async function removeInstalledSkill(path) {
+  if (!existsSync(path)) {
+    return;
+  }
+  const stat = await lstat(path);
+  if (stat.isSymbolicLink()) {
+    await unlink(path);
+    return;
+  }
+  await rm(path, { recursive: true, force: true });
+}
+
+async function materializeSkill(skillName, env = process.env, options = {}) {
+  const sourceDir = skillSourceDir(skillName, env, options.skillSourceRoot);
+  if (!existsSync(sourceDir) || !existsSync(skillSourceEntry(skillName, env, options.skillSourceRoot))) {
+    throw new Error(`missing_skill_source:${skillName}`);
+  }
+
+  const targetDir = installedSkillDir(skillName, env);
+  await ensureDir(dirname(targetDir));
+  await removeInstalledSkill(targetDir);
+
+  let installMethod = 'symlink';
+  try {
+    await symlink(sourceDir, targetDir, 'dir');
+  } catch {
+    installMethod = 'copy';
+    await cp(sourceDir, targetDir, { recursive: true });
+  }
+
+  return {
+    skillName,
+    sourceDir,
+    targetDir,
+    installMethod,
+    skillFolderHash: await fileHash(sourceDir),
+  };
+}
+
+function buildRegistryRow(record, env = process.env, options = {}) {
+  return {
+    source: 'LoopX',
+    sourceType: 'local',
+    installationIdentity: options.installationIdentity,
+    distributionChannel: options.distributionChannel,
+    sourceUrl: options.sourceUrl,
+    skillPath: `skills/${record.skillName}/SKILL.md`,
+    installedPath: record.targetDir,
+    installMethod: record.installMethod,
+    installedAt: isoNow(),
+    updatedAt: isoNow(),
+    skillFolderHash: record.skillFolderHash,
+    provenance: [
+      {
+        distributionChannel: options.distributionChannel,
+        sourceUrl: options.sourceUrl,
+      },
+    ],
+  };
+}
+
+function isLoopxOwnedIdentity(skillName, row, env = process.env) {
+  return Boolean(
+    row
+      && row.source === 'LoopX'
+      && row.sourceType === 'local'
+      && (
+        row.installationIdentity === LOOPX_INSTALLATION_IDENTITY
+        || row.sourceUrl === getProjectRoot(env)
+      )
+      && row.skillPath === `skills/${skillName}/SKILL.md`
+      && typeof row.installedPath === 'string',
+  );
+}
+
+function isLoopxOwnedRow(skillName, row, env = process.env) {
+  return Boolean(
+    isLoopxOwnedIdentity(skillName, row, env)
+      && typeof row.installedPath === 'string'
+      && row.installedPath === installedSkillDir(skillName, env),
+  );
+}
+
+async function removeStaleOwnedInstall(currentRow) {
+  if (!currentRow?.installedPath || !existsSync(currentRow.installedPath)) {
+    return;
+  }
+  await removeInstalledSkill(currentRow.installedPath);
+}
+
+async function canonicalTargetOwnership(skillName, env = process.env, options = {}) {
+  const targetDir = installedSkillDir(skillName, env);
+  const sourceDir = skillSourceDir(skillName, env, options.skillSourceRoot);
+  if (!existsSync(targetDir)) {
+    return { exists: false, owned: false };
+  }
+
+  const stat = await lstat(targetDir);
+  if (stat.isSymbolicLink()) {
+    const linkTarget = await readlink(targetDir);
+    const resolvedLink = resolve(dirname(targetDir), linkTarget);
+    return {
+      exists: true,
+      owned: resolvedLink === sourceDir,
+    };
+  }
+
+  if (stat.isDirectory()) {
+    return {
+      exists: true,
+      owned: await fileHash(targetDir) === await fileHash(sourceDir),
+    };
+  }
+
+  return { exists: true, owned: false };
+}
+
+async function assertLoopxOwnedTarget(skillName, currentRow, env = process.env, options = {}) {
+  const targetDir = installedSkillDir(skillName, env);
+  const dirExists = existsSync(targetDir);
+  const rowExists = currentRow !== null && currentRow !== undefined;
+
+  if (!dirExists && !rowExists) {
+    return { allowed: true, targetDir };
+  }
+
+  if (isLoopxOwnedIdentity(skillName, currentRow, env)) {
+    if (currentRow.installedPath !== targetDir) {
+      const canonicalTarget = await canonicalTargetOwnership(skillName, env, options);
+      if (canonicalTarget.exists && !canonicalTarget.owned) {
+        return {
+          allowed: false,
+          targetDir,
+          reason: 'canonical_target_occupied',
+        };
+      }
+      await removeStaleOwnedInstall(currentRow);
+      return {
+        allowed: true,
+        targetDir,
+        staleOwned: true,
+      };
+    }
+    return { allowed: true, targetDir };
+  }
+
+  if (!isLoopxOwnedRow(skillName, currentRow, env)) {
+    return {
+      allowed: false,
+      targetDir,
+      reason: 'foreign_or_unowned_target',
+    };
+  }
+
+  return { allowed: true, targetDir };
+}
+
+export async function inspectInstallState(env = process.env) {
+  const { data } = await readSkillLock(env);
+  const installedRoot = getInstalledSkillsRoot(env);
+  const bySkill = {};
+
+  for (const skillName of LOOPX_SKILLS) {
+    const targetDir = installedSkillDir(skillName, env);
+    const registryRow = data.skills?.[skillName] ?? null;
+    bySkill[skillName] = {
+      installedDirExists: existsSync(targetDir),
+      registryRowExists: registryRow !== null,
+      registryRow,
+      discovered: existsSync(targetDir) && isLoopxOwnedRow(skillName, registryRow, env),
+      loopxOwned: isLoopxOwnedIdentity(skillName, registryRow, env),
+    };
+  }
+
+  return {
+    projectRoot: getProjectRoot(env),
+    installedSkillsRoot: installedRoot,
+    skillLockPath: getSkillLockPath(env),
+    skills: bySkill,
+  };
+}
+
+export async function verifyInstallState(env = process.env) {
+  const inspection = await inspectInstallState(env);
+  const failures = [];
+
+  for (const skillName of LOOPX_SKILLS) {
+    const info = inspection.skills[skillName];
+    if (!info.installedDirExists) {
+      failures.push(`missing_installed_skill_dir:${skillName}`);
+    }
+    if (!info.registryRowExists) {
+      failures.push(`missing_skill_lock_row:${skillName}`);
+    }
+    if (!info.discovered) {
+      failures.push(`discovery_incomplete:${skillName}`);
+    }
+  }
+
+  return {
+    ok: failures.length === 0,
+    failures,
+    inspection,
+  };
+}
+
+export async function installBundledSkills(env = process.env, options = {}) {
+  const installOptions = getInstallOptions(options, env);
+  const { data } = await readSkillLock(env);
+  const nextData = jsonClone(data);
+  nextData.version = nextData.version || 3;
+  nextData.skills = nextData.skills || {};
+
+  const installed = [];
+  const conflicts = [];
+  for (const skillName of LOOPX_SKILLS) {
+    const current = nextData.skills[skillName];
+    const ownership = await assertLoopxOwnedTarget(skillName, current, env, installOptions);
+    if (!ownership.allowed) {
+      conflicts.push({
+        skillName,
+        reason: ownership.reason,
+        installedPath: ownership.targetDir,
+      });
+      continue;
+    }
+    const record = await materializeSkill(skillName, env, installOptions);
+    const row = buildRegistryRow(record, env, installOptions);
+    if (current?.installedAt) {
+      row.installedAt = current.installedAt;
+    }
+    if (Array.isArray(current?.provenance)) {
+      const mergedProvenance = [
+        ...current.provenance,
+        ...row.provenance,
+      ].filter((item, index, array) => array.findIndex((candidate) => candidate.distributionChannel === item.distributionChannel && candidate.sourceUrl === item.sourceUrl) === index);
+      row.provenance = mergedProvenance;
+    }
+    nextData.skills[skillName] = row;
+    installed.push(row);
+  }
+
+  await writeSkillLock(nextData, env);
+  return {
+    ok: conflicts.length === 0,
+    installed,
+    conflicts,
+    inspection: await inspectInstallState(env),
+  };
+}
+
+export async function repairBundledSkills(env = process.env) {
+  return installBundledSkills(env);
+}
+
+export const LOOPX_BUNDLED_SKILLS = LOOPX_SKILLS;

package/src/runtime-maintenance.mjs

@@ -0,0 +1,68 @@
+import { mkdir, rename } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { inspectInstallState, verifyInstallState } from './install-discovery.mjs';
+
+export function resolveLoopXRoot(cwd) {
+  return join(resolve(cwd), '.LoopX');
+}
+
+export function resolveLegacyRoot(cwd) {
+  return join(resolve(cwd), '.codex-helper');
+}
+
+export async function ensureLoopXRoot(cwd) {
+  const root = resolveLoopXRoot(cwd);
+  await mkdir(root, { recursive: true });
+  return root;
+}
+
+export async function migrateLegacyRuntime(cwd) {
+  const legacyRoot = resolveLegacyRoot(cwd);
+  const loopxRoot = resolveLoopXRoot(cwd);
+  const legacyExists = existsSync(legacyRoot);
+  const loopxExists = existsSync(loopxRoot);
+
+  if (!legacyExists) {
+    return {
+      migrated: false,
+      legacyExists: false,
+      loopxExists,
+      loopxRoot,
+      legacyRoot,
+      reason: 'legacy_root_missing',
+    };
+  }
+
+  if (loopxExists) {
+    throw new Error('mixed_runtime_roots_detected');
+  }
+
+  await rename(legacyRoot, loopxRoot);
+  return {
+    migrated: true,
+    legacyExists: true,
+    loopxExists: true,
+    loopxRoot,
+    legacyRoot,
+    reason: 'migrated_legacy_runtime',
+  };
+}
+
+export async function doctorRuntime(cwd, env = process.env) {
+  const loopxRoot = resolveLoopXRoot(cwd);
+  const legacyRoot = resolveLegacyRoot(cwd);
+  const installState = await inspectInstallState(env);
+  const installCheck = await verifyInstallState(env);
+
+  return {
+    loopxRoot,
+    legacyRoot,
+    loopxExists: existsSync(loopxRoot),
+    legacyExists: existsSync(legacyRoot),
+    mixedRuntimeRoots: existsSync(loopxRoot) && existsSync(legacyRoot),
+    installState,
+    installCheck,
+  };
+}