@refactco/refact-os 1.5.0

package/lib/project-utils.js

@@ -0,0 +1,179 @@
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline/promises");
+
+const VALID_PROJECT_TYPES = ["wordpress", "nextjs", "blank"];
+// Legacy names accepted on input and folded onto the current ones, so configs
+// and commands from before the rename keep working. "other" was renamed "blank".
+const PROJECT_TYPE_ALIASES = { other: "blank" };
+
+function normalizeProjectTypes(raw) {
+  const values = (Array.isArray(raw) ? raw : [raw]).flatMap((value) => String(value || "").split(","));
+  const seen = new Set();
+  for (const value of values) {
+    let type = String(value || "").trim().toLowerCase();
+    if (PROJECT_TYPE_ALIASES[type]) type = PROJECT_TYPE_ALIASES[type];
+    if (!VALID_PROJECT_TYPES.includes(type)) continue;
+    seen.add(type);
+  }
+  if (seen.size === 0) return [];
+  // "blank" is the no-specific-stack fallback; any real type supersedes it.
+  if (seen.size > 1 && seen.has("blank")) seen.delete("blank");
+  return [...seen];
+}
+
+function primaryProjectType(projectTypes) {
+  const normalized = normalizeProjectTypes(projectTypes);
+  return normalized[0] || "blank";
+}
+
+function detectProjectTypes(targetDir) {
+  const types = [];
+  const has = (p) => fs.existsSync(path.join(targetDir, p));
+  if (has("apps/wordpress/wp-content") || has("wp-content") || has(".wp-env.json")) {
+    types.push("wordpress");
+  }
+  if (has("next.config.js") || has("next.config.mjs") || has("next.config.ts")) {
+    types.push("nextjs");
+  }
+  try {
+    const packageJsonPath = path.join(targetDir, "package.json");
+    if (fs.existsSync(packageJsonPath)) {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+      if ((pkg.dependencies && pkg.dependencies.next) || (pkg.devDependencies && pkg.devDependencies.next)) {
+        types.push("nextjs");
+      }
+    }
+  } catch (_err) {
+    // Best effort; fall back to "blank".
+  }
+  return normalizeProjectTypes(types.length > 0 ? types : ["blank"]);
+}
+
+function detectProjectType(targetDir) {
+  return primaryProjectType(detectProjectTypes(targetDir));
+}
+
+async function askProjectTypes(defaultTypes) {
+  const normalizedDefault = normalizeProjectTypes(defaultTypes);
+  const defaultLabel = normalizedDefault.join(",") || "blank";
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const prompt = `Project type(s) [wordpress/nextjs/blank, comma-separated] (default: ${defaultLabel}): `;
+  const answer = (await rl.question(prompt)).trim().toLowerCase();
+  rl.close();
+  const parsed = normalizeProjectTypes(answer);
+  return parsed.length > 0 ? parsed : normalizedDefault;
+}
+
+async function askProjectType(defaultType) {
+  return primaryProjectType(await askProjectTypes([defaultType]));
+}
+
+function writeFile(targetPath, content, options = {}) {
+  const { force = true } = options;
+  if (!force && fs.existsSync(targetPath)) {
+    return false;
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, content, "utf8");
+  return true;
+}
+
+function _safePackageNameFromDir(targetDir) {
+  return (
+    path
+      .basename(targetDir)
+      .toLowerCase()
+      .replace(/[^a-z0-9-_.]+/g, "-")
+      .replace(/^-+/, "")
+      .replace(/-+$/, "") || "refact-project"
+  );
+}
+
+const SCAFFOLD_SCRIPTS = {
+  "chats:import": "python3 .cursor/scripts/import-project-chat-history.py",
+  "chats:import:dry": "python3 .cursor/scripts/import-project-chat-history.py --dry-run",
+  "asana:sync": "node .cursor/scripts/sync-asana.mjs",
+  "asana:sync:dry": "node .cursor/scripts/sync-asana.mjs --dry-run",
+  "refact:sync": "refact-os sync",
+  "refact:validate": "refact-os validate",
+  "refact:migrate": "refact-os migrate",
+  "refact:update": "refact-os init",
+};
+
+// refact-os is distributed from GitHub (not the npm registry). Adding it as a
+// devDependency is what lets the `refact:*` npm scripts above call the bare
+// `refact-os` binary (instead of fetching it via npx on every run).
+const SCAFFOLD_DEV_DEPENDENCIES = {
+  "refact-os": "github:refactco/refact-os",
+};
+
+// Add scaffold devDependencies that aren't already declared (in either
+// dependencies or devDependencies). Non-destructive; mutates `data` and
+// returns the names added.
+function _ensureDevDependencies(data) {
+  const depsAdded = [];
+  const deps = data.dependencies || {};
+  const devDeps = data.devDependencies || {};
+  for (const [name, spec] of Object.entries(SCAFFOLD_DEV_DEPENDENCIES)) {
+    if (name in deps || name in devDeps) continue;
+    devDeps[name] = spec;
+    depsAdded.push(name);
+  }
+  if (depsAdded.length > 0) data.devDependencies = devDeps;
+  return depsAdded;
+}
+
+function ensurePackageScripts(targetDir) {
+  const packageJsonPath = path.join(targetDir, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    const scaffoldPkg = {
+      name: _safePackageNameFromDir(targetDir),
+      version: "1.0.0",
+      private: true,
+      scripts: { ...SCAFFOLD_SCRIPTS },
+      devDependencies: { ...SCAFFOLD_DEV_DEPENDENCIES },
+    };
+    fs.writeFileSync(packageJsonPath, `${JSON.stringify(scaffoldPkg, null, 2)}\n`, "utf8");
+    return {
+      status: "created",
+      scriptsAdded: Object.keys(SCAFFOLD_SCRIPTS),
+      depsAdded: Object.keys(SCAFFOLD_DEV_DEPENDENCIES),
+    };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    const scripts = data.scripts || {};
+    const scriptsAdded = [];
+    for (const [name, command] of Object.entries(SCAFFOLD_SCRIPTS)) {
+      if (!scripts[name]) {
+        scripts[name] = command;
+        scriptsAdded.push(name);
+      }
+    }
+    const depsAdded = _ensureDevDependencies(data);
+    if (scriptsAdded.length > 0 || depsAdded.length > 0) {
+      if (scriptsAdded.length > 0) data.scripts = scripts;
+      fs.writeFileSync(packageJsonPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+      return { status: "updated", scriptsAdded, depsAdded };
+    }
+    return { status: "unchanged", scriptsAdded: [], depsAdded: [] };
+  } catch (_err) {
+    return { status: "invalid", scriptsAdded: [], depsAdded: [] };
+  }
+}
+
+module.exports = {
+  VALID_PROJECT_TYPES,
+  normalizeProjectTypes,
+  primaryProjectType,
+  detectProjectTypes,
+  detectProjectType,
+  askProjectTypes,
+  askProjectType,
+  writeFile,
+  ensurePackageScripts,
+};

package/lib/refact-config.js

@@ -0,0 +1,324 @@
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline/promises");
+const { normalizeProjectTypes, primaryProjectType } = require("./project-utils");
+
+const CONFIG_FILENAME = ".refact-os.json";
+
+// The `.refact-os.json` schema. `stack` is the single source of truth for which
+// project types this repo is: its KEYS are the type list (no separate
+// projectType/projectTypes). Each type entry carries its own hosting, runtime,
+// and per-environment deploy routing — see `stackTypeTemplate()`.
+const REQUIRED_FIELDS = [
+  {
+    path: "stack",
+    label: "Project stack",
+    type: "stack",
+    required: true,
+    prompt: "Project type(s) [wordpress/nextjs/blank, comma-separated]",
+  },
+  {
+    path: "asana.projectId",
+    label: "Asana project ID",
+    type: "string",
+    required: false,
+    prompt:
+      "Asana project ID (numeric, from app.asana.com/0/<id>/...) — leave blank or type 'skip' to mark as not used",
+  },
+];
+
+// Shape of a single `stack.<type>` entry at scaffold time. hosting/runtime are
+// filled by `/refact init`; `environments` is keyed by env name (production,
+// staging, …) with { url, branch, ssh? } each — ssh is present only for
+// SSH-push hosts (Kinsta, WP Engine) and absent for git-integration hosts
+// (Vercel, Netlify). Secrets never live here; only non-secret routing.
+function stackTypeTemplate() {
+  return { hosting: null, runtime: null, environments: {} };
+}
+
+function _get(obj, dotted) {
+  return dotted.split(".").reduce((acc, key) => (acc == null ? undefined : acc[key]), obj);
+}
+
+function _set(obj, dotted, value) {
+  const keys = dotted.split(".");
+  let cur = obj;
+  for (let i = 0; i < keys.length - 1; i += 1) {
+    const k = keys[i];
+    if (cur[k] == null || typeof cur[k] !== "object") {
+      cur[k] = {};
+    }
+    cur = cur[k];
+  }
+  cur[keys[keys.length - 1]] = value;
+}
+
+function _has(obj, dotted) {
+  const keys = dotted.split(".");
+  let cur = obj;
+  for (let i = 0; i < keys.length; i += 1) {
+    if (cur == null || typeof cur !== "object" || !(keys[i] in cur)) {
+      return false;
+    }
+    cur = cur[keys[i]];
+  }
+  return true;
+}
+
+function configPath(targetDir) {
+  return path.join(targetDir, CONFIG_FILENAME);
+}
+
+function loadConfig(targetDir) {
+  const p = configPath(targetDir);
+  if (!fs.existsSync(p)) {
+    return {};
+  }
+  try {
+    const raw = fs.readFileSync(p, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (_err) {
+    return {};
+  }
+}
+
+function saveConfig(targetDir, config) {
+  const p = configPath(targetDir);
+  fs.writeFileSync(p, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  return p;
+}
+
+// The project's type list IS the set of keys under `stack`. Returns a
+// normalized, deduped array (e.g. ["wordpress", "nextjs"]).
+function getProjectTypes(config) {
+  if (!config || !config.stack || typeof config.stack !== "object" || Array.isArray(config.stack)) {
+    return [];
+  }
+  return normalizeProjectTypes(Object.keys(config.stack));
+}
+
+function findMissingFields(config) {
+  const missing = [];
+  for (const field of REQUIRED_FIELDS) {
+    if (field.required === false) continue; // optional fields never block
+    if (field.type === "stack") {
+      // Required means: stack exists and names at least one valid type.
+      if (getProjectTypes(config).length === 0) missing.push(field);
+      continue;
+    }
+    if (_has(config, field.path)) continue;
+    missing.push(field);
+  }
+  return missing;
+}
+
+function _parseProjectTypeFromAgents(agentsContent) {
+  const match = agentsContent.match(/-\s*Project type(?:\(s\))?:\s*`([^`]+)`/m);
+  if (!match) return null;
+  const val = match[1].trim();
+  if (!val || /^<.*>$/.test(val)) return null; // ignore unfilled `<placeholder>`
+  return val;
+}
+
+// Parse a `- <Label>: \`value\`` line out of an AGENTS.md "Stack at a glance"
+// block, skipping unfilled `<placeholder>` values. Used only for migration.
+function _parseAgentsField(agentsContent, label) {
+  const esc = label.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+  const match = agentsContent.match(new RegExp(`-\\s*${esc}:\\s*\`([^\`]+)\``, "m"));
+  if (!match) return null;
+  const val = match[1].trim();
+  if (!val || /^<.*>$/.test(val)) return null;
+  return val;
+}
+
+function _readIfExists(p) {
+  try {
+    return fs.existsSync(p) ? fs.readFileSync(p, "utf8") : null;
+  } catch (_err) {
+    return null;
+  }
+}
+
+function _stripScaffoldMetadataSection(agentsContent) {
+  const lines = agentsContent.split("\n");
+  const startIdx = lines.findIndex((line) => /^##\s+Scaffold Metadata\s*$/.test(line));
+  if (startIdx === -1) return agentsContent;
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i += 1) {
+    if (/^##\s+/.test(lines[i])) {
+      endIdx = i;
+      break;
+    }
+  }
+  const before = lines.slice(0, startIdx).join("\n").replace(/\n+$/, "");
+  const after = lines.slice(endIdx).join("\n");
+  const joined = after ? `${before}\n\n${after}` : `${before}\n`;
+  return joined.replace(/\n{3,}/g, "\n\n");
+}
+
+// Ensure `config.stack` has a well-formed entry for the requested types. Existing
+// entry detail (hosting/runtime/environments) is preserved; only missing sub-keys
+// are backfilled. Invalid keys are dropped, a legacy "other" entry is migrated to
+// "blank", and a stale "blank" is removed once a real type is present.
+//
+// With `options.replace` true, `defaultTypes` is AUTHORITATIVE: any type not in it
+// is dropped (so an explicit/interactive choice can downgrade away from a
+// previously-detected stack). Without it (detection / non-interactive re-run),
+// the requested types are merged with whatever is already present.
+function ensureStack(config, defaultTypes, options = {}) {
+  const replace = options.replace === true;
+  if (!config.stack || typeof config.stack !== "object" || Array.isArray(config.stack)) {
+    config.stack = {};
+  }
+  // Migrate a legacy "other" entry to its new name "blank", preserving detail.
+  if (config.stack.other) {
+    if (!config.stack.blank) config.stack.blank = config.stack.other;
+    delete config.stack.other;
+  }
+  // Drop keys that aren't valid project types.
+  for (const key of Object.keys(config.stack)) {
+    if (normalizeProjectTypes([key]).length === 0) delete config.stack[key];
+  }
+  const wanted = normalizeProjectTypes(defaultTypes);
+  let types;
+  if (replace) {
+    types = wanted.length > 0 ? wanted : ["blank"];
+    for (const key of Object.keys(config.stack)) {
+      if (!types.includes(key)) delete config.stack[key];
+    }
+  } else {
+    const union = normalizeProjectTypes([...Object.keys(config.stack), ...wanted]);
+    types = union.length > 0 ? union : ["blank"];
+  }
+  for (const type of types) {
+    const existing = config.stack[type];
+    if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+      config.stack[type] = stackTypeTemplate();
+    } else {
+      if (!("hosting" in existing)) existing.hosting = null;
+      if (!("runtime" in existing)) existing.runtime = null;
+      if (!existing.environments || typeof existing.environments !== "object" || Array.isArray(existing.environments)) {
+        existing.environments = {};
+      }
+    }
+  }
+  // normalizeProjectTypes drops "blank" when a real type is present; mirror that
+  // in the stored stack so it doesn't linger from an earlier scaffold.
+  if (Object.keys(config.stack).length > 1 && config.stack.blank) {
+    delete config.stack.blank;
+  }
+  return config;
+}
+
+// Bring an older-schema config up to the `stack` model. Folds legacy top-level
+// `projectType` / `projectTypes` keys into `stack` and deletes them; if the
+// config still has no stack, seeds it from the AGENTS.md "Project type" prose;
+// best-effort lifts Hosting / runtime prose onto the primary type. Also strips
+// the legacy "## Scaffold Metadata" section from AGENTS.md.
+function migrateFromAgents(targetDir, config) {
+  let migrated = false;
+
+  const legacyTypeKeys = normalizeProjectTypes([
+    ...(Array.isArray(config.projectTypes) ? config.projectTypes : config.projectTypes ? [config.projectTypes] : []),
+    ...(config.projectType ? [config.projectType] : []),
+  ]);
+  if (getProjectTypes(config).length === 0 && legacyTypeKeys.length > 0) {
+    ensureStack(config, legacyTypeKeys);
+    migrated = true;
+  }
+  if ("projectType" in config) {
+    delete config.projectType;
+    migrated = true;
+  }
+  if ("projectTypes" in config) {
+    delete config.projectTypes;
+    migrated = true;
+  }
+
+  // The "Stack at a glance" prose lives in the contract (agent/AGENTS.md) in the
+  // current layout; older layouts kept it in the root AGENTS.md. Read the
+  // contract first and fall back to root for parsing.
+  const contractText = _readIfExists(path.join(targetDir, "agent", "AGENTS.md"));
+  const rootPath = path.join(targetDir, "AGENTS.md");
+  const rootText = _readIfExists(rootPath);
+  const proseSource = contractText || rootText;
+
+  if (proseSource) {
+    if (getProjectTypes(config).length === 0) {
+      const legacy = _parseProjectTypeFromAgents(proseSource);
+      if (legacy) {
+        ensureStack(config, normalizeProjectTypes(legacy));
+        migrated = true;
+      }
+    }
+    const entry = config.stack && config.stack[primaryProjectType(getProjectTypes(config))];
+    if (entry) {
+      if (entry.hosting == null) {
+        const hosting = _parseAgentsField(proseSource, "Hosting");
+        if (hosting) {
+          entry.hosting = hosting;
+          migrated = true;
+        }
+      }
+      if (entry.runtime == null) {
+        const runtime = _parseAgentsField(proseSource, "Local dev/runtime");
+        if (runtime) {
+          entry.runtime = runtime;
+          migrated = true;
+        }
+      }
+    }
+  }
+
+  // Strip the legacy "## Scaffold Metadata" section from the root AGENTS.md.
+  if (rootText != null) {
+    const stripped = _stripScaffoldMetadataSection(rootText);
+    if (stripped !== rootText) {
+      fs.writeFileSync(rootPath, stripped, "utf8");
+      return { migrated, stripped: true };
+    }
+  }
+  return { migrated, stripped: false };
+}
+
+function setAsanaProjectId(config, raw) {
+  const trimmed = (raw || "").trim();
+  if (!trimmed || /^(skip|none|n\/a)$/i.test(trimmed)) {
+    _set(config, "asana.projectId", null);
+    _set(config, "asana.projectUrl", null);
+    return config;
+  }
+  _set(config, "asana.projectId", trimmed);
+  if (/^\d+$/.test(trimmed)) {
+    _set(config, "asana.projectUrl", `https://app.asana.com/0/${trimmed}`);
+  } else {
+    _set(config, "asana.projectUrl", null);
+  }
+  return config;
+}
+
+async function askAsanaProjectId() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(
+    "Asana project ID (numeric, from app.asana.com/0/<id>/...) — leave blank to skip: ",
+  );
+  rl.close();
+  return answer;
+}
+
+module.exports = {
+  CONFIG_FILENAME,
+  REQUIRED_FIELDS,
+  stackTypeTemplate,
+  configPath,
+  loadConfig,
+  saveConfig,
+  getProjectTypes,
+  findMissingFields,
+  migrateFromAgents,
+  ensureStack,
+  setAsanaProjectId,
+  askAsanaProjectId,
+  _internal: { _get, _set, _has, _parseProjectTypeFromAgents, _parseAgentsField, _stripScaffoldMetadataSection },
+};