trackops 1.0.0

package/lib/init.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const { DEFAULT_PHASES, DEFAULT_LOCALE } = require("./config");
+const registry = require("./registry");
+const { t, setLocale } = require("./i18n");
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function parseArgs(args) {
+  const options = { locale: null, name: null, withOpera: false, phases: null };
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--locale" && args[i + 1]) { options.locale = args[i + 1]; i += 1; }
+    else if (args[i] === "--name" && args[i + 1]) { options.name = args[i + 1]; i += 1; }
+    else if (args[i] === "--with-opera" || args[i] === "--with-etapa") { options.withOpera = true; }
+    else if (args[i] === "--phases" && args[i + 1]) {
+      try { options.phases = JSON.parse(args[i + 1]); } catch (_e) { /* ignore */ }
+      i += 1;
+    }
+  }
+  return options;
+}
+
+function detectProjectName(root) {
+  const pkgPath = path.join(root, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      return pkg.displayName || pkg.name || path.basename(root);
+    } catch (_e) { /* ignore */ }
+  }
+  return path.basename(root);
+}
+
+function hasExistingOpera(root) {
+  return (
+    fs.existsSync(path.join(root, ".agent", "hub")) ||
+    fs.existsSync(path.join(root, ".agents", "skills"))
+  );
+}
+
+function buildDefaultControl(options) {
+  const locale = options.locale || DEFAULT_LOCALE;
+  setLocale(locale);
+
+  return {
+    meta: {
+      projectName: options.name || "My Project",
+      controlVersion: 2,
+      locale,
+      phases: options.phases || DEFAULT_PHASES,
+      updatedAt: nowIso(),
+      executionSource: "project_control.json",
+      currentFocus: t("init.defaultFocus"),
+      focusPhase: (options.phases || DEFAULT_PHASES)[0]?.id || "E",
+      deliveryTarget: t("init.defaultTarget"),
+    },
+    checks: {
+      lastBuild: { status: "pending", date: null, note: "" },
+      lastTest: { status: "pending", date: null, note: "" },
+      lastReview: { status: "pending", date: null, note: "" },
+    },
+    rituals: {
+      startOfSession: ["trackops status", "trackops next"],
+      beforeImplementation: ["trackops task start <task-id>"],
+      endOfSession: ["trackops task review|complete|block <task-id> <note>", "trackops sync"],
+      beforeCommit: ["trackops status", "trackops sync"],
+    },
+    milestones: [],
+    decisionsPending: [],
+    tasks: [
+      {
+        id: "ops-bootstrap",
+        title: t("init.defaultTaskTitle"),
+        phase: (options.phases || DEFAULT_PHASES)[0]?.id || "E",
+        stream: "Operations",
+        priority: "P0",
+        status: "pending",
+        required: true,
+        dependsOn: [],
+        summary: t("init.defaultTaskSummary"),
+        acceptance: [],
+        history: [{ at: nowIso(), action: "create", note: "trackops init" }],
+      },
+    ],
+    findings: [],
+  };
+}
+
+function upsertScripts(root) {
+  const pkgPath = path.join(root, "package.json");
+  let pkg = {};
+  if (fs.existsSync(pkgPath)) {
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")); } catch (_e) { /* ignore */ }
+  }
+  pkg.scripts = pkg.scripts || {};
+  Object.assign(pkg.scripts, {
+    ops: "trackops",
+    "ops:help": "trackops help",
+    "ops:dashboard": "trackops dashboard",
+    "ops:status": "trackops status",
+    "ops:next": "trackops next",
+    "ops:sync": "trackops sync",
+    "ops:repo": "trackops refresh-repo",
+  });
+  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+}
+
+function installHooks(root) {
+  const hooksDir = path.join(root, ".githooks");
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  const hookContent = "#!/bin/sh\nnpx trackops refresh-repo --quiet >/dev/null 2>&1 || true\n";
+  for (const hookName of ["post-commit", "post-checkout", "post-merge"]) {
+    const hookPath = path.join(hooksDir, hookName);
+    fs.writeFileSync(hookPath, hookContent, { mode: 0o755 });
+  }
+
+  if (fs.existsSync(path.join(root, ".git"))) {
+    spawnSync("git", ["config", "core.hooksPath", ".githooks"], { cwd: root, encoding: "utf8" });
+  }
+}
+
+function ensureTmpDir(root) {
+  const tmpDir = path.join(root, ".tmp");
+  fs.mkdirSync(tmpDir, { recursive: true });
+  const gitkeep = path.join(tmpDir, ".gitkeep");
+  if (!fs.existsSync(gitkeep)) {
+    fs.writeFileSync(gitkeep, "", "utf8");
+  }
+}
+
+function initProject(root, options) {
+  const targetRoot = path.resolve(root);
+  const controlFile = path.join(targetRoot, "project_control.json");
+  const isUpgrade = fs.existsSync(controlFile);
+
+  if (!options.name) {
+    options.name = detectProjectName(targetRoot);
+  }
+
+  if (isUpgrade) {
+    // Upgrade: add new meta fields if missing
+    const existing = JSON.parse(fs.readFileSync(controlFile, "utf8"));
+    if (!existing.meta.phases) existing.meta.phases = options.phases || DEFAULT_PHASES;
+    if (!existing.meta.locale) existing.meta.locale = options.locale || DEFAULT_LOCALE;
+    if (!existing.meta.controlVersion || existing.meta.controlVersion < 2) existing.meta.controlVersion = 2;
+    existing.meta.updatedAt = nowIso();
+    fs.writeFileSync(controlFile, `${JSON.stringify(existing, null, 2)}\n`, "utf8");
+    console.log(t("init.updated", { file: "project_control.json" }));
+  } else {
+    const control = buildDefaultControl(options);
+    fs.writeFileSync(controlFile, `${JSON.stringify(control, null, 2)}\n`, "utf8");
+    console.log(t("init.created", { file: "project_control.json" }));
+  }
+
+  upsertScripts(targetRoot);
+  console.log(t("init.updated", { file: "package.json" }));
+
+  installHooks(targetRoot);
+  console.log(t("init.created", { file: ".githooks/" }));
+
+  ensureTmpDir(targetRoot);
+
+  try {
+    registry.registerProject(targetRoot);
+    console.log(t("init.registered"));
+  } catch (_e) { /* ignore */ }
+
+  const operaDetected = hasExistingOpera(targetRoot);
+
+  console.log("");
+  console.log(t("init.welcome"));
+
+  return { root: targetRoot, isUpgrade, operaDetected };
+}
+
+function cmdInit(args) {
+  const options = parseArgs(args || []);
+  const root = process.cwd();
+  setLocale(options.locale || DEFAULT_LOCALE);
+
+  const result = initProject(root, options);
+
+  if (options.withOpera) {
+    const opera = require("./opera");
+    opera.install(root, {});
+  } else if (result.operaDetected) {
+    console.log("");
+    console.log(t("opera.primitiveDetected"));
+    console.log("  Run 'trackops opera install' to upgrade to managed OPERA.");
+  }
+}
+
+module.exports = { initProject, cmdInit, buildDefaultControl };

package/lib/opera.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const config = require("./config");
+const { t, setLocale } = require("./i18n");
+
+const TEMPLATES_DIR = path.join(__dirname, "..", "templates", "opera");
+const SKILLS_TEMPLATES_DIR = path.join(__dirname, "..", "templates", "skills");
+const OPERA_VERSION = require("../package.json").version;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function copyTemplate(templatePath, targetPath, replacements) {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  let content = fs.readFileSync(templatePath, "utf8");
+  if (replacements) {
+    for (const [key, value] of Object.entries(replacements)) {
+      content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), value);
+    }
+  }
+  fs.writeFileSync(targetPath, content, "utf8");
+}
+
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function install(root, options) {
+  const controlFile = config.controlFilePath(root);
+  if (!fs.existsSync(controlFile)) {
+    throw new Error("project_control.json not found. Run 'trackops init' first.");
+  }
+
+  const control = config.loadControl(root);
+  setLocale(config.getLocale(control));
+
+  if (config.isOperaInstalled(control)) {
+    console.log(t("opera.alreadyInstalled", { version: config.getOperaVersion(control) }));
+    return;
+  }
+
+  const projectName = control.meta.projectName || "Project";
+
+  // Create .agent/hub/ with agent.md and router.md
+  const agentHubDir = path.join(root, ".agent", "hub");
+  fs.mkdirSync(agentHubDir, { recursive: true });
+
+  const agentTemplatePath = path.join(TEMPLATES_DIR, "agent.md");
+  const routerTemplatePath = path.join(TEMPLATES_DIR, "router.md");
+
+  if (fs.existsSync(agentTemplatePath) && !fs.existsSync(path.join(agentHubDir, "agent.md"))) {
+    copyTemplate(agentTemplatePath, path.join(agentHubDir, "agent.md"), { PROJECT_NAME: projectName });
+  }
+  if (fs.existsSync(routerTemplatePath) && !fs.existsSync(path.join(agentHubDir, "router.md"))) {
+    copyTemplate(routerTemplatePath, path.join(agentHubDir, "router.md"), { PROJECT_NAME: projectName });
+  }
+
+  // Create .agent/skills/_registry.md
+  const skillsRegistryDir = path.join(root, ".agent", "skills");
+  fs.mkdirSync(skillsRegistryDir, { recursive: true });
+  const registryPath = path.join(skillsRegistryDir, "_registry.md");
+  const registryTemplatePath = path.join(TEMPLATES_DIR, "registry.md");
+  if (fs.existsSync(registryTemplatePath) && !fs.existsSync(registryPath)) {
+    copyTemplate(registryTemplatePath, registryPath, { PROJECT_NAME: projectName });
+  }
+
+  // Create genesis.md if not exists
+  const genesisTemplatePath = path.join(TEMPLATES_DIR, "genesis.md");
+  const genesisPath = path.join(root, "genesis.md");
+  if (fs.existsSync(genesisTemplatePath) && !fs.existsSync(genesisPath)) {
+    copyTemplate(genesisTemplatePath, genesisPath, { PROJECT_NAME: projectName });
+  }
+
+  // Copy OPERA references
+  const refsTemplateDir = path.join(TEMPLATES_DIR, "references");
+  if (fs.existsSync(refsTemplateDir)) {
+    const starterSkillDir = path.join(root, ".agents", "skills", "project-starter-skill", "references");
+    copyDirRecursive(refsTemplateDir, starterSkillDir);
+  }
+
+  // Install project-starter-skill SKILL.md
+  const starterSkillTemplate = path.join(SKILLS_TEMPLATES_DIR, "project-starter-skill", "SKILL.md");
+  const starterSkillTarget = path.join(root, ".agents", "skills", "project-starter-skill", "SKILL.md");
+  if (fs.existsSync(starterSkillTemplate) && !fs.existsSync(starterSkillTarget)) {
+    fs.mkdirSync(path.dirname(starterSkillTarget), { recursive: true });
+    fs.copyFileSync(starterSkillTemplate, starterSkillTarget);
+  }
+
+  // Mark as installed in control
+  control.meta.opera = {
+    installed: true,
+    version: OPERA_VERSION,
+    installedAt: nowIso(),
+    skills: [],
+  };
+  config.saveControl(root, control);
+
+  console.log(t("opera.installed", { version: OPERA_VERSION }));
+
+  // Auto-install base skills (commiter, changelog-updater)
+  const skills = require("./skills");
+  for (const skillName of ["commiter", "changelog-updater"]) {
+    try { skills.installSkill(root, skillName); }
+    catch (_e) { /* already installed or not in catalog — skip silently */ }
+  }
+}
+
+function status(root) {
+  const control = config.loadControl(root);
+  setLocale(config.getLocale(control));
+
+  if (!config.isOperaInstalled(control)) {
+    console.log(t("opera.notInstalled"));
+    return;
+  }
+
+  const opera = control.meta.opera;
+  console.log(`OPERA v${opera.version}`);
+  console.log(`  Installed: ${opera.installedAt}`);
+  console.log(`  Skills: ${(opera.skills || []).join(", ") || "none"}`);
+
+  // Check structural integrity
+  const checks = [
+    [".agent/hub/agent.md", fs.existsSync(path.join(root, ".agent", "hub", "agent.md"))],
+    [".agent/hub/router.md", fs.existsSync(path.join(root, ".agent", "hub", "router.md"))],
+    [".agent/skills/_registry.md", fs.existsSync(path.join(root, ".agent", "skills", "_registry.md"))],
+    ["genesis.md", fs.existsSync(path.join(root, "genesis.md"))],
+  ];
+
+  console.log("  Structure:");
+  for (const [file, exists] of checks) {
+    console.log(`    ${exists ? "\u2705" : "\u274C"} ${file}`);
+  }
+}
+
+function configure(root, args) {
+  const control = config.loadControl(root);
+  setLocale(config.getLocale(control));
+
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--locale" && args[i + 1]) {
+      control.meta.locale = args[i + 1];
+      i += 1;
+    }
+    if (args[i] === "--phases" && args[i + 1]) {
+      try {
+        control.meta.phases = JSON.parse(args[i + 1]);
+      } catch (_e) {
+        console.error("Invalid phases JSON.");
+        return;
+      }
+      i += 1;
+    }
+  }
+
+  config.saveControl(root, control);
+  console.log("Configuration updated.");
+}
+
+function upgrade(root) {
+  const control = config.loadControl(root);
+  setLocale(config.getLocale(control));
+
+  if (!config.isOperaInstalled(control)) {
+    console.log(t("opera.notInstalled"));
+    console.log("Run 'trackops opera install' first.");
+    return;
+  }
+
+  // Re-copy reference files
+  const refsTemplateDir = path.join(TEMPLATES_DIR, "references");
+  if (fs.existsSync(refsTemplateDir)) {
+    const starterSkillDir = path.join(root, ".agents", "skills", "project-starter-skill", "references");
+    copyDirRecursive(refsTemplateDir, starterSkillDir);
+  }
+
+  control.meta.opera.version = OPERA_VERSION;
+  config.saveControl(root, control);
+  console.log(t("opera.upgraded", { version: OPERA_VERSION }));
+}
+
+/* ── CLI commands ── */
+
+function cmdInstall(root, args) { install(root, {}); }
+function cmdStatus(root) { status(root); }
+function cmdConfigure(root, args) { configure(root, args); }
+function cmdUpgrade(root) { upgrade(root); }
+
+module.exports = { install, status, configure, upgrade, cmdInstall, cmdStatus, cmdConfigure, cmdUpgrade };

package/lib/registry.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const { t } = require("./i18n");
+
+const REGISTRY_DIR = path.join(os.homedir(), ".codex", "trackops");
+const REGISTRY_FILE = path.join(REGISTRY_DIR, "registry.json");
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function slugify(value) {
+  return String(value || "")
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+}
+
+function shortHash(value) {
+  let hash = 0;
+  const input = String(value || "");
+  for (let index = 0; index < input.length; index += 1) {
+    hash = (hash * 31 + input.charCodeAt(index)) >>> 0;
+  }
+  return hash.toString(36).slice(0, 6);
+}
+
+function ensureRegistryDir() {
+  fs.mkdirSync(REGISTRY_DIR, { recursive: true });
+}
+
+function loadRegistry() {
+  ensureRegistryDir();
+  if (!fs.existsSync(REGISTRY_FILE)) {
+    return { version: 1, updatedAt: nowIso(), projects: [] };
+  }
+  return JSON.parse(fs.readFileSync(REGISTRY_FILE, "utf8"));
+}
+
+function saveRegistry(registry) {
+  ensureRegistryDir();
+  registry.updatedAt = nowIso();
+  fs.writeFileSync(REGISTRY_FILE, `${JSON.stringify(registry, null, 2)}\n`, "utf8");
+}
+
+function isProjectInstalled(rootDir) {
+  return fs.existsSync(path.join(rootDir, "project_control.json"));
+}
+
+function inspectProject(rootDir) {
+  const root = path.resolve(rootDir);
+  const controlStateFile = path.join(root, "project_control.json");
+
+  if (!fs.existsSync(controlStateFile)) {
+    throw new Error(`Project '${root}' does not have trackops installed.`);
+  }
+
+  let packageJson = {};
+  const packageFile = path.join(root, "package.json");
+  if (fs.existsSync(packageFile)) {
+    packageJson = JSON.parse(fs.readFileSync(packageFile, "utf8"));
+  }
+
+  const controlState = JSON.parse(fs.readFileSync(controlStateFile, "utf8"));
+  const projectName =
+    controlState.meta?.projectName || packageJson.displayName || packageJson.name || path.basename(root);
+
+  return {
+    id: `${slugify(projectName) || "project"}-${shortHash(root)}`,
+    name: projectName,
+    root,
+    packageName: packageJson.name || null,
+    controlStateFile,
+    registeredAt: nowIso(),
+    lastSeenAt: nowIso(),
+  };
+}
+
+function registerProject(rootDir) {
+  const registry = loadRegistry();
+  const entry = inspectProject(rootDir);
+  const existingIndex = registry.projects.findIndex((p) => p.root === entry.root);
+
+  if (existingIndex >= 0) {
+    registry.projects[existingIndex] = {
+      ...registry.projects[existingIndex],
+      ...entry,
+      registeredAt: registry.projects[existingIndex].registeredAt || entry.registeredAt,
+      lastSeenAt: nowIso(),
+    };
+  } else {
+    registry.projects.push(entry);
+  }
+
+  registry.projects.sort((a, b) => a.name.localeCompare(b.name));
+  saveRegistry(registry);
+  return registry.projects.find((p) => p.root === entry.root);
+}
+
+function unregisterProject(rootDir) {
+  const root = path.resolve(rootDir);
+  const registry = loadRegistry();
+  registry.projects = registry.projects.filter((p) => p.root !== root);
+  saveRegistry(registry);
+  return registry;
+}
+
+function listProjects() {
+  const registry = loadRegistry();
+  return registry.projects.map((project) => {
+    const available = isProjectInstalled(project.root);
+    return { ...project, available };
+  });
+}
+
+function resolveProject(projectRef, fallbackRoot) {
+  const projects = listProjects();
+
+  if (!projectRef) {
+    if (fallbackRoot) {
+      return projects.find((p) => p.root === path.resolve(fallbackRoot)) || null;
+    }
+    return projects[0] || null;
+  }
+
+  const normalizedRef = path.resolve(projectRef);
+  return (
+    projects.find((p) => p.id === projectRef) ||
+    projects.find((p) => p.root === normalizedRef) ||
+    null
+  );
+}
+
+/* ── CLI commands ── */
+
+function cmdRegister(root) {
+  const project = registerProject(root);
+  console.log(`${t("init.registered")} ${project.name}`);
+  console.log(project.root);
+}
+
+function cmdList() {
+  const projects = listProjects();
+  if (!projects.length) {
+    console.log("No registered projects.");
+    return;
+  }
+  projects.forEach((project, index) => {
+    console.log(`${index + 1}. ${project.name}`);
+    console.log(`   id: ${project.id}`);
+    console.log(`   root: ${project.root}`);
+    console.log(`   available: ${project.available ? "yes" : "no"}`);
+  });
+}
+
+function cmdWhere() {
+  console.log(REGISTRY_FILE);
+}
+
+module.exports = {
+  REGISTRY_DIR,
+  REGISTRY_FILE,
+  inspectProject,
+  isProjectInstalled,
+  listProjects,
+  loadRegistry,
+  registerProject,
+  resolveProject,
+  saveRegistry,
+  slugify,
+  unregisterProject,
+  cmdRegister,
+  cmdList,
+  cmdWhere,
+};