@kylecheng3146/agent-ops 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Cheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# Loop Engineering Toolkit
+
+Loop Engineering Toolkit is an evidence-driven development-loop toolkit for
+Codex and Claude Code. It is designed to turn acceptance criteria, explicit
+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.
+
+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.
+
+## 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:
+
+```bash
+git clone https://github.com/kylecheng3146/agent-ops.git
+cd agent-ops
+npm ci
+npm run build
+node dist/packages/cli/src/bin.js --version
+```
+
+Preview a project installation before changing files:
+
+```bash
+node dist/packages/cli/src/bin.js init \
+  --dry-run --scope project --harness both --profile core --json
+```
+
+After reviewing the plan, apply it explicitly with `--yes`. Trust, diagnostics,
+updates, and removal are separate commands:
+
+```bash
+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 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.
+
+## Project principles
+
+- Define verifiable success before making changes.
+- Treat command output and current filesystem state as evidence.
+- Keep advisory automation separate from blocking guardrails.
+- Preserve user configuration through managed, reversible updates.
+- Support Codex and Claude Code without project-specific assumptions.
+- Collect no network telemetry.
+
+## 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.
+
+Documentation:
+
+- [English specification](docs/en/spec/README.md)
+- [繁體中文規範](docs/zh-TW/spec/README.md)
+- [English guides](docs/en/guides/quickstart.md)
+- [繁體中文指南](docs/zh-TW/guides/quickstart.md)
+
+## Community
+
+- Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change.
+- Report security issues according to [SECURITY.md](SECURITY.md).
+- Participation is governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## License
+
+Copyright (c) 2026 Kyle Cheng. Released under the [MIT License](LICENSE).

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported versions
+
+The project has not published a supported release yet. Development branches
+and pre-1.0 artifacts are provided for evaluation and do not carry an SLA.
+Supported release lines and security-fix policy will be listed before version
+1.0.0.
+
+## Reporting a vulnerability
+
+Do not disclose suspected vulnerabilities in a public issue. Use GitHub's
+private vulnerability reporting interface for this repository when available.
+If that interface is unavailable, contact the maintainer through the public
+contact method listed on the
+[kylecheng3146 GitHub profile](https://github.com/kylecheng3146) and request a
+private reporting channel. Do not include exploit details in the initial public
+message.
+
+Reports should include the affected version, impact, minimal reproduction, and
+any known mitigation. No response-time or remediation SLA is currently
+promised.

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

@@ -0,0 +1,322 @@
+export const COMMAND_NAMES = [
+    "init",
+    "config",
+    "trust",
+    "doctor",
+    "update",
+    "uninstall",
+    "task",
+    "verify",
+    "review"
+];
+const COMMAND_SET = new Set(COMMAND_NAMES);
+const SCOPES = new Set(["project", "user"]);
+const HARNESSES = new Set(["both", "claude", "codex"]);
+const PROFILES = new Set(["advisory", "core", "guardrails"]);
+export class CliArgumentError extends Error {
+    code;
+    option;
+    constructor(code, message, option) {
+        super(message);
+        this.name = "CliArgumentError";
+        this.code = code;
+        this.option = option;
+    }
+}
+function readOptionValue(argv, index, option) {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+        throw new CliArgumentError("CLI_MISSING_VALUE", `${option} requires a value.`, option);
+    }
+    return value;
+}
+function duplicate(option) {
+    throw new CliArgumentError("CLI_DUPLICATE_OPTION", `${option} may not be repeated.`, option);
+}
+function invalidValue(option, value) {
+    throw new CliArgumentError("CLI_INVALID_VALUE", `Invalid value for ${option}: ${value}`, option);
+}
+export function parseArgs(argv) {
+    let command;
+    let action;
+    let scope;
+    let harness;
+    let taskId;
+    let targetVersion;
+    let title;
+    let sessionId;
+    const profiles = [];
+    const criteria = [];
+    const evidence = [];
+    let dryRun = false;
+    let json = false;
+    let yes = false;
+    let helpSeen = false;
+    let versionSeen = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === undefined) {
+            break;
+        }
+        switch (token) {
+            case "--scope": {
+                if (scope !== undefined) {
+                    duplicate(token);
+                }
+                const value = readOptionValue(argv, index, token);
+                if (!SCOPES.has(value)) {
+                    invalidValue(token, value);
+                }
+                scope = value;
+                index += 1;
+                break;
+            }
+            case "--harness": {
+                if (harness !== undefined) {
+                    duplicate(token);
+                }
+                const value = readOptionValue(argv, index, token);
+                if (!HARNESSES.has(value)) {
+                    invalidValue(token, value);
+                }
+                harness = value;
+                index += 1;
+                break;
+            }
+            case "--profile": {
+                const value = readOptionValue(argv, index, token);
+                if (!PROFILES.has(value)) {
+                    invalidValue(token, value);
+                }
+                if (profiles.includes(value)) {
+                    duplicate(`${token} ${value}`);
+                }
+                profiles.push(value);
+                index += 1;
+                break;
+            }
+            case "--task": {
+                if (taskId !== undefined) {
+                    duplicate(token);
+                }
+                taskId = readOptionValue(argv, index, token);
+                index += 1;
+                break;
+            }
+            case "--target-version": {
+                if (targetVersion !== undefined) {
+                    duplicate(token);
+                }
+                targetVersion = readOptionValue(argv, index, token);
+                index += 1;
+                break;
+            }
+            case "--title": {
+                if (title !== undefined) {
+                    duplicate(token);
+                }
+                title = readOptionValue(argv, index, token);
+                index += 1;
+                break;
+            }
+            case "--criterion": {
+                criteria.push(readOptionValue(argv, index, token));
+                index += 1;
+                break;
+            }
+            case "--evidence": {
+                evidence.push(readOptionValue(argv, index, token));
+                index += 1;
+                break;
+            }
+            case "--session": {
+                if (sessionId !== undefined) {
+                    duplicate(token);
+                }
+                sessionId = readOptionValue(argv, index, token);
+                index += 1;
+                break;
+            }
+            case "--dry-run":
+                if (dryRun) {
+                    duplicate(token);
+                }
+                dryRun = true;
+                break;
+            case "--json":
+                if (json) {
+                    duplicate(token);
+                }
+                json = true;
+                break;
+            case "--yes":
+                if (yes) {
+                    duplicate(token);
+                }
+                yes = true;
+                break;
+            case "--help":
+            case "-h":
+                if (helpSeen) {
+                    duplicate(token);
+                }
+                helpSeen = true;
+                break;
+            case "--version":
+            case "-v":
+                if (versionSeen) {
+                    duplicate(token);
+                }
+                versionSeen = true;
+                break;
+            default:
+                if (token.startsWith("-")) {
+                    throw new CliArgumentError("CLI_UNKNOWN_OPTION", `Unknown option: ${token}`, token);
+                }
+                if (command === "config" &&
+                    action === undefined &&
+                    token === "explain") {
+                    action = token;
+                    break;
+                }
+                if (command === "trust" &&
+                    action === undefined &&
+                    ["grant", "revoke", "status"].includes(token)) {
+                    action = token;
+                    break;
+                }
+                if (command === "task" &&
+                    action === undefined &&
+                    [
+                        "archive",
+                        "attach",
+                        "complete",
+                        "create",
+                        "export",
+                        "status"
+                    ].includes(token)) {
+                    action = token;
+                    break;
+                }
+                if (command !== undefined) {
+                    throw new CliArgumentError("CLI_UNEXPECTED_ARGUMENT", `Unexpected argument: ${token}`);
+                }
+                if (!COMMAND_SET.has(token)) {
+                    throw new CliArgumentError("CLI_UNKNOWN_COMMAND", `Unknown command: ${token}`);
+                }
+                command = token;
+        }
+    }
+    if (helpSeen && versionSeen) {
+        throw new CliArgumentError("CLI_CONFLICTING_ACTION", "--help and --version cannot be combined.");
+    }
+    if ((helpSeen || versionSeen) && command !== undefined) {
+        throw new CliArgumentError("CLI_CONFLICTING_ACTION", "Global help or version cannot be combined with a command.");
+    }
+    if (helpSeen || versionSeen) {
+        if (scope !== undefined ||
+            harness !== undefined ||
+            profiles.length > 0 ||
+            taskId !== undefined ||
+            targetVersion !== undefined ||
+            title !== undefined ||
+            criteria.length > 0 ||
+            evidence.length > 0 ||
+            sessionId !== undefined ||
+            dryRun ||
+            yes) {
+            throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Only --json may be combined with global help or version.");
+        }
+        command = helpSeen ? "help" : "version";
+    }
+    if (command === undefined) {
+        throw new CliArgumentError("CLI_COMMAND_REQUIRED", "A command, --help, or --version is required.");
+    }
+    if (command === "trust" && action === undefined) {
+        throw new CliArgumentError("CLI_ACTION_REQUIRED", "The trust command requires one of: status, grant, revoke.");
+    }
+    if (command === "task" && action === undefined) {
+        throw new CliArgumentError("CLI_ACTION_REQUIRED", "The task command requires one of: create, status, attach, complete, archive, export.");
+    }
+    const hasTaskTargetOptions = taskId !== undefined ||
+        sessionId !== undefined;
+    const hasTaskMutationOptions = title !== undefined ||
+        criteria.length > 0 ||
+        evidence.length > 0;
+    if (command !== "task" &&
+        command !== "verify" &&
+        command !== "review" &&
+        (hasTaskTargetOptions || hasTaskMutationOptions)) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Task target options may be used only with task or verify.");
+    }
+    if (command !== "update" && targetVersion !== undefined) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--target-version may be used only with update.");
+    }
+    if (command === "task") {
+        if (harness !== undefined ||
+            profiles.length > 0 ||
+            dryRun ||
+            yes) {
+            throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Task commands do not accept harness, profile, dry-run, or yes options.");
+        }
+        const taskOptionInvalid = (action === "create" &&
+            (taskId !== undefined ||
+                evidence.length > 0 ||
+                sessionId !== undefined)) ||
+            (action === "status" &&
+                (title !== undefined ||
+                    criteria.length > 0 ||
+                    evidence.length > 0 ||
+                    (taskId !== undefined && sessionId !== undefined))) ||
+            (action === "attach" &&
+                (title !== undefined ||
+                    criteria.length > 0 ||
+                    evidence.length > 0)) ||
+            (action === "complete" &&
+                (title !== undefined ||
+                    criteria.length > 0 ||
+                    sessionId !== undefined)) ||
+            ((action === "archive" || action === "export") &&
+                (title !== undefined ||
+                    criteria.length > 0 ||
+                    evidence.length > 0 ||
+                    sessionId !== undefined));
+        if (taskOptionInvalid) {
+            throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", `Unsupported option for task ${action}.`);
+        }
+    }
+    if (command === "verify" &&
+        (harness !== undefined ||
+            profiles.length > 0 ||
+            title !== undefined ||
+            criteria.length > 0 ||
+            evidence.length > 0 ||
+            dryRun ||
+            yes ||
+            (taskId !== undefined && sessionId !== undefined))) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Verify accepts only scope, task or session, and json options.");
+    }
+    if (command === "review" &&
+        (title !== undefined || sessionId !== undefined)) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Review accepts harness, criteria, evidence, scope, dry-run, json, and yes options.");
+    }
+    if (command === "review" && harness === "both") {
+        invalidValue("--harness", harness);
+    }
+    return {
+        command,
+        ...(action === undefined ? {} : { action }),
+        ...(scope === undefined ? {} : { scope }),
+        ...(harness === undefined ? {} : { harness }),
+        profiles,
+        ...(taskId === undefined ? {} : { taskId }),
+        ...(targetVersion === undefined ? {} : { targetVersion }),
+        ...(title === undefined ? {} : { title }),
+        ...(criteria.length === 0 ? {} : { criteria }),
+        ...(evidence.length === 0 ? {} : { evidence }),
+        ...(sessionId === undefined ? {} : { sessionId }),
+        dryRun,
+        json,
+        yes
+    };
+}