@kylecheng3146/agent-ops 0.0.1 → 0.1.2

package/README.md

@@ -6,17 +6,66 @@ verification, safe lifecycle hooks, and independent review into a repeatable
 engineering workflow.
 
 This repository is in its foundation stage. The CLI, hook runtime, normative
-specification, and installation profiles are being developed in a reviewable
-feature branch before the first pre-1.0 release.
+specification, and installation profiles are being developed as a reviewable
+pre-1.0 interface.
 
-The current CLI is an unreleased development interface. Its packed artifact is
-checked by `npm run package:check`; command behavior may change before the first
-tagged pre-1.0 release.
+The CLI is published as `@kylecheng3146/agent-ops` as a pre-1.0 interface;
+command behavior may change before 1.0.
+
+## Quick start from npm
+
+Requires Node.js `>=22.14.0`. Install the published CLI globally:
+
+```bash
+npm install --global @kylecheng3146/agent-ops@latest
+agent-ops --version
+```
+
+You can run it without a global install with `npx`. When the command runs in
+an interactive terminal without arguments, it opens the setup wizard
+automatically:
+
+```bash
+npx --yes @kylecheng3146/agent-ops@latest
+```
+
+Use `--help` for the complete command reference or provide explicit options in
+automation. The wizard never writes files until you review and confirm its
+installation plan.
+
+Preview a project installation before changing files:
+
+```bash
+agent-ops init \
+  --dry-run --scope project --harness both --profile core --json
+```
+
+After reviewing the plan, apply it explicitly with `--yes`:
+
+```bash
+agent-ops init --scope project --harness both --profile core --yes
+```
+
+The remaining day-to-day checks are:
+
+```bash
+agent-ops trust status --json
+agent-ops doctor --json
+agent-ops config explain --json
+agent-ops update --dry-run --json
+agent-ops update --yes --json
+agent-ops uninstall --dry-run --json
+```
+
+Use `--scope user` with user-home installations. Keep `--dry-run` for any
+operation you want to inspect before applying; non-interactive automation should
+pass `--yes` only after reviewing the plan. Add `--json` when another tool will
+consume the result.
 
 ## Quick start from a source checkout
 
-Version 0.1.0 is prepared for release but has not yet been published to npm.
-Until the protected release workflow completes, use a source checkout:
+For development or to run the repository version directly, use a source
+checkout:
 
 ```bash
 git clone https://github.com/kylecheng3146/agent-ops.git
@@ -40,16 +89,17 @@ updates, and removal are separate commands:
 node dist/packages/cli/src/bin.js init --scope project --harness both --profile core --yes
 node dist/packages/cli/src/bin.js trust status --json
 node dist/packages/cli/src/bin.js doctor --json
-node dist/packages/cli/src/bin.js update --target-version 0.1.0 --dry-run --json
+node dist/packages/cli/src/bin.js config explain --json
+node dist/packages/cli/src/bin.js update --dry-run --json
 node dist/packages/cli/src/bin.js uninstall --dry-run --json
 ```
 
 The commands after `init --yes` are post-apply operations; `doctor` may report
 an unknown probe status until a repository-specific verification setup exists.
 
-Use `--scope user` with user-home installations. Do not install from npm until
-the `v0.1.0` tag has been published; the release workflow is the source of the
-published package and provenance record.
+For a full command reference, run `agent-ops --help`. The `task`, `verify`, and
+`review` commands support acceptance tracking and independent verification when
+the project configuration defines those workflows.
 
 ## Project principles
 
@@ -62,8 +112,9 @@ published package and provenance record.
 
 ## Project status
 
-No npm package has been published yet. Do not depend on the current repository
-as a stable interface until a tagged release is available.
+A pre-1.0 npm package is published. Use `@latest` for the current release, or
+pin a specific version in automation when reproducibility matters; review
+release notes before upgrading.
 
 Documentation:
 

package/dist/packages/cli/src/bin.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { execFileSync } from "node:child_process";
 import { commonHarnessAdapters } from "../../../runtime/src/install/harness.js";
+import { hookRegistrationSatisfied, repositoryTrustStatus, smokeAvailabilityStatus } from "../../../runtime/src/install/probes.js";
+import { parseInstallManifest } from "../../../runtime/src/fs/manifest.js";
 import { NpmRegistryClient } from "../../../runtime/src/registry/npm.js";
 import { TaskService } from "../../../runtime/src/task/service.js";
 import { FileTaskStore } from "../../../runtime/src/task/store.js";
@@ -28,7 +31,7 @@ import { runTrustCommand } from "./commands/trust.js";
 import { runVerifyCommand } from "./commands/verify.js";
 import { formatUpdatePlan, runUpdateCommand } from "./commands/update.js";
 import { errorEnvelope } from "./output.js";
-const CLI_VERSION = "0.1.0";
+const CLI_VERSION = "0.1.2";
 const DEFAULT_CONFIG = {
     schemaVersion: 1,
     profiles: [],
@@ -95,6 +98,23 @@ async function loadEffectiveConfig(root, scope) {
     }
     return mergeConfigLayers(layers);
 }
+async function readOptionalJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function installedHarness(root) {
+    try {
+        return parseInstallManifest(await readFile(join(root, ".agent-ops", "manifest.json"), "utf8")).harness;
+    }
+    catch {
+        // ponytail: no readable manifest means demand hooks for both harnesses.
+        return "both";
+    }
+}
 async function repositoryTrust(root, config) {
     const home = process.env.AGENT_OPS_HOME ?? homedir();
     const state = localStatePaths(home);
@@ -175,7 +195,20 @@ process.exitCode = await runCli(process.argv.slice(2), {
                 });
             }
             if (args.command === "doctor") {
-                return await runDoctorCommand({ root });
+                const config = (await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project")).config;
+                return await runDoctorCommand({
+                    root,
+                    probes: {
+                        hookRegistration: async () => hookRegistrationSatisfied({
+                            harness: await installedHarness(root),
+                            profiles: config.profiles,
+                            claudeSettings: await readOptionalJson(join(root, ".claude", "settings.json")),
+                            codexHooks: await readOptionalJson(join(root, ".codex", "hooks.json"))
+                        }),
+                        repositoryTrust: async () => repositoryTrustStatus(await repositoryTrust(root, config)),
+                        smokeAvailability: () => smokeAvailabilityStatus(config)
+                    }
+                });
             }
             if (args.command === "uninstall") {
                 return await runUninstallCommand({

package/dist/packages/cli/src/cli.js

@@ -1,8 +1,22 @@
 import { CliArgumentError, parseArgs } from "./args.js";
 import { errorEnvelope, okEnvelope, writeEnvelope } from "./output.js";
 import { completeInitChoices } from "./wizard.js";
+const WELCOME_BANNER = [
+    "+--------------------------------------------------+",
+    "|          LOOP ENGINEERING TOOLKIT               |",
+    "|       Safe setup for Codex + Claude Code         |",
+    "+--------------------------------------------------+"
+].join("\n");
+export function renderWelcome(color) {
+    const cyan = color ? "\u001b[36m" : "";
+    const bold = color ? "\u001b[1m" : "";
+    const reset = color ? "\u001b[0m" : "";
+    return `${cyan}${bold}${WELCOME_BANNER}${reset}\n\n`;
+}
 export const HELP_TEXT = `Usage: agent-ops <command> [options]
 
+Run \`agent-ops\` without arguments in a terminal to start the interactive setup wizard.
+
 Commands:
   init       Plan or install agent-ops
   config explain
@@ -41,10 +55,15 @@ function writeAndReturn(io, envelope, json, exitCode) {
     return exitCode;
 }
 export async function runCli(argv, io, services) {
-    const json = wantsJson(argv);
+    const launchesWizard = argv.length === 0 && io.isTTY;
+    const effectiveArgv = launchesWizard ? ["init"] : argv;
+    if (launchesWizard) {
+        io.writeStdout(renderWelcome(process.env.NO_COLOR === undefined && process.env.TERM !== "dumb"));
+    }
+    const json = wantsJson(effectiveArgv);
     let args;
     try {
-        args = parseArgs(argv);
+        args = parseArgs(effectiveArgv);
     }
     catch (error) {
         if (error instanceof CliArgumentError) {

package/dist/runtime/src/fs/transaction.js

@@ -6,6 +6,17 @@ import { fileURLToPath } from "node:url";
 import { sha256 } from "./hash.js";
 import { AgentOpsError, resolveContainedPath } from "./paths.js";
 export { AgentOpsError } from "./paths.js";
+/**
+ * Identity must come from bigint stats. Windows file indexes pack a sequence
+ * number above the 2^53 boundary, so a numeric `ino` silently rounds and an
+ * untouched file looks like it changed.
+ */
+export function fileIdentity(status) {
+    return {
+        device: status.dev.toString(),
+        inode: status.ino.toString()
+    };
+}
 const MUTATION_WORKER_PATH = fileURLToPath(new URL("./mutation-worker.js", import.meta.url));
 function isMissing(error) {
     return (typeof error === "object" &&
@@ -25,10 +36,11 @@ async function captureParentGuard(parent) {
         normalizedPath(canonicalPath) !== normalizedPath(parent)) {
         throw new AgentOpsError("PRECONDITION_CHANGED", `Destination directory changed before mutation: ${parent}`);
     }
+    const identity = fileIdentity(status);
     return {
         expectedParentPath: canonicalPath,
-        parentDevice: status.dev.toString(),
-        parentInode: status.ino.toString()
+        parentDevice: identity.device,
+        parentInode: identity.inode
     };
 }
 async function runAnchoredMutation(targetPath, action, expectedHash, content, mode) {
@@ -162,20 +174,21 @@ async function createBackup(snapshot, recoveryDirectory) {
 async function snapshotOperation(root, operation) {
     const targetPath = await resolveContainedPath(root, operation.path);
     try {
-        const status = await lstat(targetPath);
+        const status = await lstat(targetPath, { bigint: true });
         if (!status.isFile()) {
             throw new AgentOpsError("UNSUPPORTED_FILE_TYPE", `Managed target must be a regular file: ${operation.path}`);
         }
         const content = await readFile(targetPath);
+        const identity = fileIdentity(status);
         return {
             operation,
             targetPath,
             existed: true,
             content,
-            mode: status.mode & 0o777,
+            mode: Number(status.mode) & 0o777,
             actualHash: sha256(content),
-            device: status.dev.toString(),
-            inode: status.ino.toString(),
+            device: identity.device,
+            inode: identity.inode,
             backupPath: null,
             createdDirectories: []
         };
@@ -219,10 +232,7 @@ async function currentIdentity(path) {
         if (!status.isFile() || status.isSymbolicLink()) {
             throw new AgentOpsError("PRECONDITION_CHANGED", `A managed path is no longer a regular file: ${path}`);
         }
-        return {
-            device: status.dev.toString(),
-            inode: status.ino.toString()
-        };
+        return fileIdentity(status);
     }
     catch (error) {
         if (isMissing(error)) {

package/dist/runtime/src/install/doctor.js

@@ -165,9 +165,13 @@ async function checkProbe(id, probe) {
         return check(id, "UNKNOWN", "No probe was provided.");
     }
     try {
-        return (await probe())
-            ? check(id, "PASS", "Probe passed.")
-            : check(id, "FAIL", "Probe failed.");
+        const result = await probe();
+        const status = typeof result === "boolean" ? (result ? "PASS" : "FAIL") : result;
+        return check(id, status, status === "PASS"
+            ? "Probe passed."
+            : status === "FAIL"
+                ? "Probe failed."
+                : "Probe has nothing to verify yet.");
     }
     catch {
         return check(id, "FAIL", "Probe failed.");

package/dist/runtime/src/install/probes.js

@@ -0,0 +1,68 @@
+import { buildClaudeHookSettings } from "../adapters/claude/config.js";
+import { buildCodexHookConfig } from "../adapters/codex/config.js";
+import { resolveProfiles } from "./profiles.js";
+const CLAUDE_HOOK_MARKER = "--managed-by=agent-ops";
+const CODEX_COMMAND_PREFIX = "agent-ops hook codex ";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasManagedHandler(source, events, isManaged) {
+    if (!isRecord(source) || !isRecord(source.hooks)) {
+        return false;
+    }
+    const registered = source.hooks;
+    return events.every((event) => {
+        const groups = registered[event];
+        return (Array.isArray(groups) &&
+            groups.some((group) => isRecord(group) &&
+                Array.isArray(group.hooks) &&
+                group.hooks.some(isManaged)));
+    });
+}
+function isManagedClaudeHandler(handler) {
+    return (isRecord(handler) &&
+        Array.isArray(handler.args) &&
+        handler.args.includes(CLAUDE_HOOK_MARKER));
+}
+function isManagedCodexHandler(handler) {
+    return (isRecord(handler) &&
+        typeof handler.command === "string" &&
+        handler.command.startsWith(CODEX_COMMAND_PREFIX));
+}
+/**
+ * Hook registration is satisfied when every hook event implied by the
+ * installed profiles carries an agent-ops owned handler for every installed
+ * harness. Installations without hook capabilities have nothing to register.
+ */
+export function hookRegistrationSatisfied(input) {
+    const { capabilities } = resolveProfiles(input.profiles);
+    const claudeEvents = Object.keys(buildClaudeHookSettings(capabilities, "probe").hooks);
+    const codexEvents = Object.keys(buildCodexHookConfig(capabilities).hooks);
+    if (claudeEvents.length === 0 && codexEvents.length === 0) {
+        return true;
+    }
+    if (input.harness !== "codex" &&
+        !hasManagedHandler(input.claudeSettings, claudeEvents, isManagedClaudeHandler)) {
+        return false;
+    }
+    return (input.harness === "claude" ||
+        hasManagedHandler(input.codexHooks, codexEvents, isManagedCodexHandler));
+}
+/**
+ * Smoke availability stays UNKNOWN until the repository declares a
+ * verification command; the toolkit never invents one.
+ */
+export function smokeAvailabilityStatus(config) {
+    return config.verification.commands.length > 0 ? "PASS" : "UNKNOWN";
+}
+/**
+ * Installation approval never grants trust, so an ungranted repository is
+ * unconfigured rather than broken. A stale binding is a real failure.
+ */
+export function repositoryTrustStatus(trust) {
+    return trust === "TRUSTED"
+        ? "PASS"
+        : trust === "STALE"
+            ? "FAIL"
+            : "UNKNOWN";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.0.1",
+  "version": "0.1.2",
   "description": "Evidence-driven development loops for Codex and Claude Code",
   "type": "module",
   "license": "MIT",