feature-loop-harness-cli 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# Feature Loop Harness CLI
+![image](https://res.cloudinary.com/dddvvp9de/image/upload/v1780124834/FeatureLoopHarness_zndch9.png)
+
+npx installer CLI for Feature Loop Harness, a Codex workflow guardrail template.
+
+For more details, or if you prefer the clone-based installation flow, see [jkuminga/FeatureLoopHarness](https://github.com/jkuminga/FeatureLoopHarness).
+
+## Usage
+
+Run the installer from the root of a new or early-stage project:
+
+```sh
+npx feature-loop-harness-cli init
+```
+
+Or target a specific directory:
+
+```sh
+npx feature-loop-harness-cli init --target ./my-project
+```
+
+The installer copies the harness template, merges npm scripts and dev dependencies into `package.json`, initializes Git when needed, runs `npm install`, installs Husky metadata, and runs a lightweight verification pass.
+
+## Options
+
+```text
+init [directory]
+  --target <path>     Install into a target directory.
+  --force             Overwrite existing harness files when conflicts are found.
+  --skip-install      Do not run npm install or Husky setup.
+  --skip-verify       Do not run the verification commands.
+  --skip-git          Do not run git init when the target has no .git directory.
+  --dry-run           Print planned actions without writing files.
+  -h, --help          Show help.
+```
+
+## After Install
+
+Codex project-local hook approval still requires an explicit user action. From the target project root:
+
+```sh
+codex
+/hooks
+```
+
+Approve the `UserPromptSubmit` hook after checking that it points to `.codex/hooks/user-prompt-submit.sh`.
+
+## Development
+
+```sh
+npm test
+npm pack
+```

package/bin/flh.js

@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "templates", "default");
+const OPTIONAL_SKIP_IF_EXISTS = new Set(["README.md"]);
+
+function printHelp() {
+  console.log(`Feature Loop Harness CLI
+
+Usage:
+  flh init [directory] [options]
+  feature-loop-harness-cli init [directory] [options]
+
+Options:
+  --target <path>     Install into a target directory.
+  --force             Overwrite existing harness files when conflicts are found.
+  --skip-install      Do not run npm install or Husky setup.
+  --skip-verify       Do not run verification commands.
+  --skip-git          Do not run git init when the target has no .git directory.
+  --dry-run           Print planned actions without writing files.
+  -h, --help          Show help.
+`);
+}
+
+function fail(message) {
+  console.error(`flh: ${message}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  if (args.includes("-h") || args.includes("--help")) {
+    return { help: true };
+  }
+
+  const command = args[0] && !args[0].startsWith("-") ? args.shift() : "init";
+  const options = {
+    target: null,
+    force: false,
+    skipInstall: false,
+    skipVerify: false,
+    skipGit: false,
+    dryRun: false,
+  };
+  let positionalTarget = null;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--target") {
+      options.target = args[index + 1];
+      index += 1;
+    } else if (arg.startsWith("--target=")) {
+      options.target = arg.slice("--target=".length);
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (arg === "--skip-install") {
+      options.skipInstall = true;
+    } else if (arg === "--skip-verify") {
+      options.skipVerify = true;
+    } else if (arg === "--skip-git") {
+      options.skipGit = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (!arg.startsWith("-") && positionalTarget === null) {
+      positionalTarget = arg;
+    } else {
+      fail(`unknown option: ${arg}`);
+    }
+  }
+
+  options.target = options.target || positionalTarget || ".";
+  return { command, options };
+}
+
+function listFiles(root) {
+  const result = [];
+
+  function walk(current) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        result.push(fullPath);
+      }
+    }
+  }
+
+  walk(root);
+  return result;
+}
+
+function relativeTemplatePath(filePath) {
+  return path.relative(TEMPLATE_ROOT, filePath).split(path.sep).join("/");
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function writeJson(filePath, value, dryRun) {
+  if (dryRun) {
+    console.log(`[dry-run] write ${filePath}`);
+    return;
+  }
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function ensureDirectory(dir, dryRun) {
+  if (dryRun) {
+    console.log(`[dry-run] mkdir -p ${dir}`);
+    return;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyFile(src, dest, dryRun) {
+  if (dryRun) {
+    console.log(`[dry-run] copy ${relativeTemplatePath(src)} -> ${dest}`);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  fs.chmodSync(dest, fs.statSync(src).mode & 0o777);
+}
+
+function mergeGitignore(templatePath, targetPath, dryRun) {
+  const templateLines = fs
+    .readFileSync(templatePath, "utf8")
+    .split(/\r?\n/)
+    .filter(Boolean);
+
+  if (!fs.existsSync(targetPath)) {
+    copyFile(templatePath, targetPath, dryRun);
+    return;
+  }
+
+  const current = fs.readFileSync(targetPath, "utf8");
+  const currentLines = new Set(current.split(/\r?\n/).map((line) => line.trim()));
+  const missing = templateLines.filter((line) => !currentLines.has(line.trim()));
+
+  if (missing.length === 0) {
+    console.log("gitignore: already contains harness ignore rules");
+    return;
+  }
+
+  if (dryRun) {
+    console.log(`[dry-run] append ${missing.length} entries to ${targetPath}`);
+    return;
+  }
+
+  const separator = current.endsWith("\n") ? "" : "\n";
+  fs.appendFileSync(targetPath, `${separator}\n# Feature Loop Harness\n${missing.join("\n")}\n`, "utf8");
+  console.log(`gitignore: appended ${missing.length} harness ignore rules`);
+}
+
+function copyTemplate(targetDir, options) {
+  const files = listFiles(TEMPLATE_ROOT);
+  const conflicts = [];
+
+  for (const src of files) {
+    const rel = relativeTemplatePath(src);
+    const dest = path.join(targetDir, rel);
+
+    if (rel === "gitignore.template" || OPTIONAL_SKIP_IF_EXISTS.has(rel)) {
+      continue;
+    }
+
+    if (fs.existsSync(dest) && !options.force) {
+      conflicts.push(rel);
+    }
+  }
+
+  if (conflicts.length > 0) {
+    fail(
+      [
+        "target already contains harness files:",
+        ...conflicts.map((file) => `  - ${file}`),
+        "rerun with --force only if overwriting is intended.",
+      ].join("\n")
+    );
+  }
+
+  for (const src of files) {
+    const rel = relativeTemplatePath(src);
+    const dest = path.join(targetDir, rel);
+
+    if (rel === "gitignore.template") {
+      mergeGitignore(src, path.join(targetDir, ".gitignore"), options.dryRun);
+      continue;
+    }
+
+    if (OPTIONAL_SKIP_IF_EXISTS.has(rel) && fs.existsSync(dest) && !options.force) {
+      console.log(`${rel}: kept existing file`);
+      continue;
+    }
+
+    copyFile(src, dest, options.dryRun);
+  }
+}
+
+function packageNameFromDirectory(targetDir) {
+  const fallback = "feature-loop-project";
+  const name = path.basename(targetDir).toLowerCase();
+  const normalized = name
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || fallback;
+}
+
+function mergePackageJson(targetDir, dryRun) {
+  const packagePath = path.join(targetDir, "package.json");
+  const exists = fs.existsSync(packagePath);
+  const pkg = exists
+    ? readJson(packagePath)
+    : {
+        name: packageNameFromDirectory(targetDir),
+        version: "0.1.0",
+        private: true,
+      };
+
+  pkg.scripts = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  pkg.devDependencies =
+    pkg.devDependencies && typeof pkg.devDependencies === "object" ? pkg.devDependencies : {};
+
+  if (!pkg.scripts["flh:test"]) {
+    pkg.scripts["flh:test"] =
+      "python3 -m unittest tests/hooks/test_user_prompt_submit.py tests/hooks/test_pre_commit.py";
+  }
+
+  if (!pkg.scripts["flh:precommit"]) {
+    pkg.scripts["flh:precommit"] = "python3 .flh/scripts/pre_commit.py";
+  }
+
+  if (!pkg.scripts.test) {
+    pkg.scripts.test = "npm run flh:test";
+  }
+
+  if (!pkg.scripts.prepare) {
+    pkg.scripts.prepare = "husky";
+  } else if (!String(pkg.scripts.prepare).includes("husky")) {
+    console.log("package.json: kept existing prepare script; run `npx husky` manually if needed");
+  }
+
+  const allDependencies = {
+    ...(pkg.dependencies || {}),
+    ...(pkg.devDependencies || {}),
+  };
+
+  if (!allDependencies.husky) {
+    pkg.devDependencies.husky = "^9.1.7";
+  }
+
+  if (!allDependencies["lint-staged"]) {
+    pkg.devDependencies["lint-staged"] = "^17.0.6";
+  }
+
+  if (!pkg["lint-staged"] || typeof pkg["lint-staged"] !== "object") {
+    pkg["lint-staged"] = {};
+  }
+
+  if (!pkg["lint-staged"]["*.{js,jsx,ts,tsx}"]) {
+    pkg["lint-staged"]["*.{js,jsx,ts,tsx}"] = ["eslint --fix", "prettier --write"];
+  }
+
+  writeJson(packagePath, pkg, dryRun);
+  console.log(`${exists ? "updated" : "created"} package.json`);
+}
+
+function runCommand(command, args, cwd, options) {
+  const printable = [command, ...args].join(" ");
+  if (options.dryRun) {
+    console.log(`[dry-run] ${printable}`);
+    return;
+  }
+
+  console.log(`running: ${printable}`);
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: "inherit",
+    shell: false,
+  });
+
+  if (result.status !== 0) {
+    fail(`${printable} failed with exit code ${result.status}`);
+  }
+}
+
+function runHookSmoke(targetDir, dryRun) {
+  const hookPath = path.join(targetDir, ".codex", "hooks", "user-prompt-submit.sh");
+  if (dryRun) {
+    console.log(`[dry-run] ${hookPath} < /q hook smoke test`);
+    return;
+  }
+
+  const result = spawnSync(hookPath, {
+    cwd: targetDir,
+    input: "/q hook smoke test\n",
+    text: true,
+    encoding: "utf8",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (result.status !== 0) {
+    process.stdout.write(result.stdout || "");
+    process.stderr.write(result.stderr || "");
+    fail(`hook smoke test failed with exit code ${result.status}`);
+  }
+
+  console.log("hook smoke test passed");
+}
+
+function initGit(targetDir, options) {
+  if (options.skipGit) {
+    return;
+  }
+
+  if (fs.existsSync(path.join(targetDir, ".git"))) {
+    console.log("git: existing repository detected");
+    return;
+  }
+
+  runCommand("git", ["init"], targetDir, options);
+}
+
+function installDependencies(targetDir, options) {
+  if (options.skipInstall) {
+    console.log("npm install: skipped");
+    return;
+  }
+
+  runCommand("npm", ["install"], targetDir, options);
+  runCommand("npx", ["husky"], targetDir, options);
+}
+
+function verifyInstall(targetDir, options) {
+  if (options.skipVerify) {
+    console.log("verification: skipped");
+    return;
+  }
+
+  runCommand("npm", ["run", "flh:test"], targetDir, options);
+  runHookSmoke(targetDir, options.dryRun);
+}
+
+function printNextSteps(targetDir) {
+  console.log(`
+Feature Loop Harness installed in:
+  ${targetDir}
+
+Next steps:
+  1. Run: codex
+  2. Inside Codex, run: /hooks
+  3. Approve the UserPromptSubmit hook after checking .codex/hooks/user-prompt-submit.sh.
+`);
+}
+
+function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  if (parsed.command !== "init") {
+    fail(`unknown command: ${parsed.command}`);
+  }
+
+  if (!fs.existsSync(TEMPLATE_ROOT)) {
+    fail(`template directory is missing: ${TEMPLATE_ROOT}`);
+  }
+
+  const targetDir = path.resolve(process.cwd(), parsed.options.target);
+  ensureDirectory(targetDir, parsed.options.dryRun);
+  copyTemplate(targetDir, parsed.options);
+  mergePackageJson(targetDir, parsed.options.dryRun);
+  initGit(targetDir, parsed.options);
+  installDependencies(targetDir, parsed.options);
+  verifyInstall(targetDir, parsed.options);
+  printNextSteps(targetDir);
+}
+
+main();

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "feature-loop-harness-cli",
+  "version": "0.1.0",
+  "description": "npx installer CLI for Feature Loop Harness, a Codex workflow guardrail template.",
+  "license": "ISC",
+  "type": "commonjs",
+  "bin": {
+    "flh": "bin/flh.js",
+    "feature-loop-harness-cli": "bin/flh.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node bin/flh.js --help && npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "codex",
+    "workflow",
+    "harness",
+    "npx",
+    "cli"
+  ]
+}

package/templates/default/.codex/config.toml

@@ -0,0 +1,2 @@
+[features]
+hooks = true

package/templates/default/.codex/hooks/user-prompt-submit.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+exec python3 "$ROOT/.flh/hooks/user_prompt_submit.py"

package/templates/default/.codex/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".codex/hooks/user-prompt-submit.sh",
+            "statusMessage": "Checking harness workflow state",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}