@clawops/cli 1.7.1 → 1.7.3

package/dist/{server-RGLKKCCU.js → server-L22AJQZO.js}

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
+import {
+  applyPlan
+} from "./chunk-5SPESD5N.js";
+import "./chunk-6ZFIFDBJ.js";
+import "./chunk-BOPSG2LI.js";
 import {
   extractBaseOutputs
 } from "./chunk-3QJBNAHW.js";
 import {
   generatePlan
-} from "./chunk-FQ4JXUCR.js";
-import {
-  applyPlan
-} from "./chunk-ISFHLA4G.js";
+} from "./chunk-NESXDU5F.js";
 import {
   validatePlan
-} from "./chunk-YTH4L2GN.js";
-import "./chunk-6ZFIFDBJ.js";
-import "./chunk-BOPSG2LI.js";
+} from "./chunk-6X45DDGH.js";
 import {
   errText,
   formatUptime,
@@ -23,16 +23,17 @@ import {
   handleConfigValidate,
   okText,
   resolveConn
-} from "./chunk-CG3Y7Y2R.js";
-import "./chunk-ZFNPM2WG.js";
-import {
-  buildContext
-} from "./chunk-3MFZ7E74.js";
+} from "./chunk-FSUWPL7Q.js";
 import {
   acquireSession,
   drainPool
-} from "./chunk-LCKD7L7X.js";
-import "./chunk-GJEF6UQA.js";
+} from "./chunk-DQDAWNGB.js";
+import "./chunk-O3F7OGH7.js";
+import {
+  buildContext
+} from "./chunk-P5LKWRPL.js";
+import "./chunk-PVUVI35Y.js";
+import "./chunk-3XK66DKK.js";
 import "./chunk-Q7NQY5HV.js";
 import "./chunk-A2I76FTA.js";
 import {
@@ -535,7 +536,7 @@ async function handleGatewayRestart(input, server) {
     const cmd = [
       "docker stop openclaw 2>/dev/null || true",
       "docker rm   openclaw 2>/dev/null || true",
-      `docker run -d --name openclaw --restart unless-stopped -p 18789:18789 ${image}`
+      `docker run -d --name openclaw --restart unless-stopped -p 18789:18789 -e OPENCLAW_CONFIG_PATH=/app/config.json --add-host=host.docker.internal:host-gateway -v /home/clawops/openclaw.json:/app/config.json:ro ${image}`
     ].join(" && ");
     const result = await session.exec(cmd);
     if (result.code !== 0) {
@@ -631,7 +632,7 @@ async function handleUp(input, server) {
       );
     }
     const { localOpts } = stackConfig;
-    const { localBootstrap } = await import("./bootstrap-RY4VOSDJ.js");
+    const { localBootstrap } = await import("./bootstrap-HL4DNUNG.js");
     const ac = new AbortController();
     const state = await localBootstrap({
       host: localOpts.host,
@@ -854,7 +855,7 @@ async function handleTaskStatus(input, _server) {
 
 // src/mcp/tools/cli/monitor.ts
 async function handleMonitor(input, _server) {
-  const { acquireSession: acquireSession2, drainPool: drainPool2 } = await import("./pool-JZGKPP6K.js");
+  const { acquireSession: acquireSession2, drainPool: drainPool2 } = await import("./pool-QGFQRMGU.js");
   const ctx = buildContext({ stack: input.stackName });
   const tailLines = input.tailLines ?? 5;
   let conn;
@@ -1306,7 +1307,7 @@ If none of the above resolves the issue:
 
 // src/mcp/server.ts
 async function serveMcp(opts) {
-  const { version } = await import("./package-OMPI6RMV.js");
+  const { version } = await import("./package-QE7V2JAT.js");
   const server = new McpServer({ name: "clawops", version });
   registerTools(server, opts);
   registerResources(server);

package/dist/{ssh-E2AMBPZY.js → ssh-CNJNLM3E.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   connect
-} from "./chunk-GJEF6UQA.js";
+} from "./chunk-3XK66DKK.js";
 import "./chunk-KGXPLI7W.js";
 export {
   connect

package/dist/{validate-T5M5EHSJ.js → validate-CFQ4FH2T.js}

@@ -2,7 +2,8 @@
 import {
   assertValidPlan,
   validatePlan
-} from "./chunk-YTH4L2GN.js";
+} from "./chunk-6X45DDGH.js";
+import "./chunk-PVUVI35Y.js";
 export {
   assertValidPlan,
   validatePlan

package/dist/version-guard-MZAO4KHS.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import {
+  assertSupportedVersion,
+  loadVersionSpec
+} from "./chunk-2YOP6N7X.js";
+import "./chunk-PVUVI35Y.js";
+import {
+  UsageError
+} from "./chunk-KGXPLI7W.js";
+
+// src/cli/version-guard.ts
+async function defaultOpenclawVersion() {
+  const yaml = await import("./js-yaml-PTEEG4FO.js");
+  return loadVersionSpec(yaml).support.recommended;
+}
+async function guardOpenclawVersion(version, resolver) {
+  const yaml = await import("./js-yaml-PTEEG4FO.js");
+  const result = await assertSupportedVersion(version, yaml, resolver);
+  if (result.ok) return result.value;
+  throw new UsageError(result.error.message);
+}
+export {
+  defaultOpenclawVersion,
+  guardOpenclawVersion
+};

package/dist/versions-OEPAS2EL.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import {
+  MOVING_TAGS,
+  _resetVersionSpecCache,
+  assertSupportedVersion,
+  checkVersion,
+  compareVersions,
+  describeRange,
+  isMovingTag,
+  loadVersionSpec,
+  resolveVersion
+} from "./chunk-2YOP6N7X.js";
+import "./chunk-PVUVI35Y.js";
+export {
+  MOVING_TAGS,
+  _resetVersionSpecCache,
+  assertSupportedVersion,
+  checkVersion,
+  compareVersions,
+  describeRange,
+  isMovingTag,
+  loadVersionSpec,
+  resolveVersion
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawops/cli",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Deploy and manage self-hosted OpenClaw instances across clouds",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
     ".": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "spec"
   ],
   "repository": {
     "type": "git",

package/spec/_gen-schemas.md

@@ -0,0 +1,136 @@
+# Schema Code Generation — `pnpm gen:schemas`
+
+This document specifies the contract for `scripts/gen-schemas.ts`, the codegen pipeline that emits TypeScript types and Zod schemas from the machine-readable specs in `spec/`.
+
+## Why This Exists
+
+R-meta-1 declares schema files as ground truth. To make this enforceable rather than aspirational, generated TypeScript artifacts must mechanically derive from the schemas. CI verifies no drift via `pnpm gen:schemas --check`.
+
+## Inputs
+
+| File | Format | Purpose |
+|---|---|---|
+| `spec/providers.schema.json` | JSON Schema | Drives `ProviderAdapter` interface |
+| `spec/mcp-tools.yaml` | YAML | Drives MCP tool Zod schemas + tool registration |
+| `spec/deploy-plan.schema.json` | JSON Schema | Drives `DeployPlan` type + ajv validator |
+| `spec/errors.yaml` | YAML | Drives error class hierarchy + taxonomy IDs |
+| `spec/openclaw-versions.yaml` | YAML | Drives version compatibility check |
+| `spec/invariants.yaml` | YAML | Drives invariants test runner |
+
+## Outputs
+
+| File | Source | Purpose |
+|---|---|---|
+| `src/providers/types.ts` | `providers.schema.json` | `ProviderAdapter` TS interface |
+| `src/providers/_schema.ts` | `providers.schema.json` | Embedded JSON Schema for runtime ajv |
+| `src/mcp/tools/_generated.ts` | `mcp-tools.yaml` | Zod schemas for every tool's input/output, tool registration helper |
+| `src/plan/_schema.ts` | `deploy-plan.schema.json` | Embedded JSON Schema for `apply` validation |
+| `src/plan/types.ts` | `deploy-plan.schema.json` | TS types for `DeployPlan` |
+| `src/errors/_generated.ts` | `errors.yaml` | Error class hierarchy, taxonomy IDs as enums |
+| `src/openclaw/versions.ts` | `openclaw-versions.yaml` | Version constants and quirks lookup |
+
+All generated files MUST start with a banner comment:
+
+```typescript
+// AUTO-GENERATED by scripts/gen-schemas.ts. DO NOT EDIT.
+// Source: spec/<filename>
+// Run `pnpm gen:schemas` to regenerate.
+```
+
+## Behavior
+
+### `pnpm gen:schemas`
+
+1. Read all input files
+2. Parse and validate each against its meta-schema (JSON Schema validates JSON Schema; YAML files validate against `spec/_meta/*.schema.json`)
+3. For each output file:
+   a. Generate the new content
+   b. Compare to existing file (if present)
+   c. Write if different; preserve mtime if identical
+4. Format output via `prettier --config .prettierrc <files>`
+5. Exit 0 on success; non-zero on any validation failure
+
+### `pnpm gen:schemas --check`
+
+Same as above, but step 3c becomes:
+- If existing file differs from new content: print diff + exit 1
+- If files match: exit 0
+
+This is the CI mode — fails the build if generated files are stale.
+
+## Tooling
+
+- **JSON Schema → TypeScript:** `json-schema-to-typescript`
+- **JSON Schema → Zod:** `json-schema-to-zod`
+- **YAML parsing:** `yaml` package
+- **Diff display:** `diff` package + colorized output
+- **Formatting:** `prettier` (programmatic API)
+
+## Validation Rules
+
+The generator MUST enforce:
+
+1. **Provider schema:**
+   - Every provider name in the enum must have an implementation under `src/providers/<name>/` (warning if missing; not error, to allow scaffolding)
+   - Every required field has a `description`
+
+2. **MCP tools:**
+   - All tool names start with `clawops_` (R1, I5)
+   - Total tool count ≤ 30 (R1, I4)
+   - Every tool has all four annotation hints set explicitly (R10, I3)
+   - Every description contains "Do NOT use" substring (R3, I6)
+   - Every tool is in at least one toolset
+
+3. **Deploy plan schema:**
+   - `apiVersion` is a const literal (semantic versioning safety)
+   - `secrets[]` items only allow `ref`, never `value` (R6 enforcement)
+
+4. **Errors:**
+   - Every taxonomy ID maps to exactly one class
+   - Class IDs in the taxonomy must exist in the `classes` list
+
+If any validation fails, the generator exits non-zero with a clear error message before writing anything.
+
+## Running in CI
+
+In `.github/workflows/ci.yml`:
+
+```yaml
+- name: Verify generated files are up-to-date
+  run: pnpm gen:schemas --check
+```
+
+This runs BEFORE typecheck so failures surface clearly.
+
+## Editor Integration
+
+For local dev, recommend adding a watcher (in CONTRIBUTING.md):
+
+```bash
+# Watch spec/ and regenerate on change
+pnpm exec chokidar 'spec/**/*' -c 'pnpm gen:schemas'
+```
+
+## Failure Modes and Recovery
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| `gen:schemas --check` fails after spec edit | Forgot to commit generated files | Run `pnpm gen:schemas`, commit |
+| Generator throws "validation failed" | Spec violates meta-schema | Fix the spec to match meta-schema |
+| Generated TS doesn't typecheck | Generator template bug | File issue; revert to last working commit |
+| Tool count exceeds 30 | New MCP tool tipped over R1 | Move a tool to a different toolset, deprecate, or merge |
+| Tool missing "Do NOT use" | Description doesn't include negative guidance | Update spec entry; R3 violation |
+
+## Versioning the Generator Itself
+
+The generator's logic is part of the project's interface contract. Major changes to its output format MUST be accompanied by:
+
+1. An ADR documenting the format change
+2. A migration script if downstream code is affected
+3. A CHANGELOG entry
+
+## Future Extensions (Not in v1)
+
+- Generate OpenAPI spec for the standalone HTTP MCP server from `spec/mcp-tools.yaml`
+- Generate Markdown docs for each provider/tool/error from the specs
+- Generate JSON Schema for `~/.clawops/config.json` from `spec/config.schema.json` (not yet authored)

package/spec/deploy-plan.schema.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clawops.dev/schemas/deploy-plan.json",
+  "title": "DeployPlan",
+  "description": "The Maker plan artifact (borrowed from Clanker pattern). Generated by `clawops plan`, applied by `clawops apply`. Reviewable, diff-able, version-controllable.",
+  "type": "object",
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "properties": {
+    "apiVersion": {
+      "const": "clawops.dev/v1",
+      "description": "Schema version pinning"
+    },
+    "kind": {
+      "const": "DeployPlan"
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["name", "generatedAt"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,62}$",
+          "description": "Stack name"
+        },
+        "generatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp"
+        },
+        "generator": {
+          "type": "string",
+          "default": "clawops",
+          "description": "Tool that produced this plan; agents can identify themselves here"
+        },
+        "generatorVersion": {
+          "type": "string",
+          "description": "semver of generator"
+        },
+        "labels": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "User-supplied labels (env=prod, team=platform, etc.)"
+        },
+        "stackVersion": {
+          "type": "integer",
+          "description": "Pulumi stack version at plan generation time (from UpdateSummary.version). Compared at apply time to detect drift. Absent for new stacks with no history."
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "required": ["provider", "stackName", "instanceType", "openclaw", "network"],
+      "properties": {
+        "provider": {
+          "enum": ["aws", "gcp", "azure", "local"]
+        },
+        "region": {
+          "type": "string",
+          "description": "Cloud region. Required for non-local providers"
+        },
+        "stackName": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,62}$"
+        },
+        "instanceType": {
+          "type": "string",
+          "description": "Provider-native instance type. Adapter normalizes from clawops alias before plan emission"
+        },
+        "openclaw": {
+          "type": "object",
+          "required": ["version"],
+          "properties": {
+            "version": {
+              "type": "string",
+              "description": "semver or 'stable'/'dev'"
+            },
+            "config": {
+              "type": "object",
+              "description": "Overrides applied on top of default openclaw.json. Secrets must use $secret references, never inline values"
+            },
+            "channels": {
+              "type": "object",
+              "description": "OpenClaw channel integrations keyed by provider name (e.g. {\"discord\":{\"botToken\":\"...\"}}). Values are provider-specific config objects. Sensitive fields must use $secret references.",
+              "additionalProperties": { "type": "object" }
+            }
+          }
+        },
+        "secrets": {
+          "type": "array",
+          "description": "Secret references (R6: never inline values)",
+          "items": {
+            "type": "object",
+            "required": ["name", "source"],
+            "properties": {
+              "name": { "type": "string" },
+              "source": {
+                "enum": ["env", "aws-sm", "aws-ssm", "gcp-sm", "azure-kv", "file"]
+              },
+              "ref": {
+                "type": "string",
+                "description": "Source-specific reference (env var name, ARN, secret URI, file path)"
+              }
+            }
+          }
+        },
+        "network": {
+          "type": "object",
+          "required": ["allowedSshCidrs", "allowedGatewayCidrs"],
+          "properties": {
+            "allowedSshCidrs": {
+              "type": "array",
+              "items": { "type": "string", "format": "cidr" },
+              "minItems": 0,
+              "description": "Empty array = no SSH access (unusual but allowed). Defaults applied at plan generation, not in schema"
+            },
+            "allowedGatewayCidrs": {
+              "type": "array",
+              "items": { "type": "string", "format": "cidr" },
+              "description": "CIDRs allowed to reach the OpenClaw gateway port (default 18789)"
+            },
+            "tailscale": {
+              "type": "object",
+              "description": "Optional Tailscale sidecar (borrowed pattern from schmitthub)",
+              "properties": {
+                "enabled": { "type": "boolean" },
+                "authKeyRef": { "type": "string", "description": "Reference to a secret containing the Tailscale auth key" }
+              }
+            }
+          }
+        },
+        "ssh": {
+          "type": "object",
+          "properties": {
+            "publicKey": {
+              "type": "string",
+              "description": "Public key contents (safe to inline). Private key never in plan"
+            },
+            "user": { "type": "string", "default": "ubuntu" }
+          }
+        },
+        "tags": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Cloud-resource tags propagated to all created resources"
+        }
+      }
+    },
+    "diff": {
+      "type": "object",
+      "description": "Optional resource diff populated by `clawops plan` for human review. Not used by `apply`",
+      "properties": {
+        "create": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ResourceRef" }
+        },
+        "update": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["resource", "before", "after"],
+            "properties": {
+              "resource": { "$ref": "#/$defs/ResourceRef" },
+              "before": {},
+              "after": {}
+            }
+          }
+        },
+        "delete": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ResourceRef" }
+        },
+        "totalChanges": { "type": "integer" }
+      }
+    }
+  },
+  "$defs": {
+    "ResourceRef": {
+      "type": "object",
+      "required": ["urn", "type"],
+      "properties": {
+        "urn": {
+          "type": "string",
+          "description": "Pulumi URN, e.g., urn:pulumi:prod::clawops::clawops:app:Gateway::main-gateway"
+        },
+        "type": {
+          "type": "string",
+          "description": "Pulumi resource type token"
+        },
+        "name": { "type": "string" }
+      }
+    }
+  }
+}

package/spec/errors.yaml

@@ -0,0 +1,175 @@
+# Error Taxonomy — machine-readable companion to ADR 0005.
+# Used by `pnpm gen:schemas` to emit src/errors/_generated.ts.
+# Update via PR; CI verifies generated file matches.
+
+version: 1
+
+# Top-level error classes; each maps to an exit code (ADR 0005).
+classes:
+  - id: UsageError
+    exitCode: 2
+    description: User input is invalid; user must change input
+    retryable: false
+    userActionRequired: true
+
+  - id: AuthError
+    exitCode: 3
+    description: Credentials missing, invalid, or insufficient
+    retryable: false
+    userActionRequired: true
+
+  - id: StateError
+    exitCode: 4
+    description: clawops-managed state is corrupt or inconsistent
+    retryable: false
+    userActionRequired: true
+
+  - id: ProviderError
+    exitCode: 5
+    description: Cloud provider rejected the request (non-auth)
+    retryable: depends   # per-taxon
+    userActionRequired: depends
+
+  - id: NetworkError
+    exitCode: 6
+    description: Network connectivity failure
+    retryable: true
+    userActionRequired: false
+
+  - id: OperationalError
+    exitCode: 1
+    description: Operation-time error during a valid operation
+    retryable: depends
+    userActionRequired: depends
+
+  - id: CancelledError
+    exitCode: 130
+    description: User-initiated cancellation
+    retryable: true
+    userActionRequired: false
+
+# Specific taxonomy IDs that errors must use as their `errorClass` field.
+# Every thrown ClawopsError MUST have one of these IDs.
+taxonomy:
+  # Usage
+  - id: usage.invalid_flag
+    class: UsageError
+    suggestedAction: "Check the flag spelling and value with `clawops <command> --help`."
+  - id: usage.missing_arg
+    class: UsageError
+    suggestedAction: "Provide the missing argument; see `clawops <command> --help`."
+  - id: usage.invalid_path
+    class: UsageError
+    suggestedAction: "Provide an absolute path. Relative paths are not accepted (R7)."
+  - id: usage.invalid_plan
+    class: UsageError
+    suggestedAction: "Plan failed schema validation. Regenerate with `clawops plan`."
+
+  # Auth
+  - id: auth.no_credentials
+    class: AuthError
+    suggestedAction: "Run `clawops init` to configure credentials."
+  - id: auth.expired
+    class: AuthError
+    suggestedAction: "Re-authenticate with your cloud provider; for AWS run `aws sso login`."
+  - id: auth.insufficient_permissions
+    class: AuthError
+    suggestedAction: "The configured credentials lack required IAM permissions; see docs/providers/<name>.md."
+
+  # State
+  - id: state.lock_held
+    class: StateError
+    suggestedAction: "Another clawops operation may be in progress; wait or run `clawops stacks unlock <name>` if certain it's stale."
+  - id: state.signature_mismatch
+    class: StateError
+    suggestedAction: "The plan file has been modified since generation; regenerate with `clawops plan`."
+  - id: state.backend_unreachable
+    class: StateError
+    suggestedAction: "Cannot reach the state backend (e.g., S3 bucket); verify access and connectivity."
+  - id: state.corrupt
+    class: StateError
+    suggestedAction: "State file is corrupt; consider `clawops state recover` or contact support."
+
+  # Provider
+  - id: provider.quota_exceeded
+    class: ProviderError
+    retryable: true
+    suggestedAction: "Cloud quota exceeded; wait or request a quota increase from your provider."
+  - id: provider.region_unsupported
+    class: ProviderError
+    retryable: false
+    userActionRequired: true
+    suggestedAction: "Selected region does not support the requested resource; choose a different region."
+  - id: provider.api_rate_limited
+    class: ProviderError
+    retryable: true
+    suggestedAction: "Cloud API rate-limited; clawops will retry with backoff."
+  - id: provider.resource_not_found
+    class: ProviderError
+    retryable: false
+    suggestedAction: "Required cloud resource not found; check stack state with `clawops status`."
+  - id: provider.resource_exists
+    class: ProviderError
+    retryable: false
+    suggestedAction: "Resource with this name already exists; use `--stack` to deploy to a different name."
+
+  # Network
+  - id: network.timeout
+    class: NetworkError
+    suggestedAction: "Network timeout; check connectivity and retry."
+  - id: network.dns_failure
+    class: NetworkError
+    suggestedAction: "DNS resolution failed; check DNS configuration."
+  - id: network.tls_failure
+    class: NetworkError
+    retryable: false
+    userActionRequired: true
+    suggestedAction: "TLS handshake failed; check certificate validity and trust chain."
+
+  # Operational
+  - id: op.timeout
+    class: OperationalError
+    retryable: true
+    suggestedAction: "Operation timed out; retry. If persistent, increase timeout via --timeout flag."
+  - id: op.unexpected_state
+    class: OperationalError
+    retryable: false
+    suggestedAction: "Cloud resource in unexpected state; run `clawops refresh` then `clawops status`."
+  - id: op.openclaw_unhealthy
+    class: OperationalError
+    retryable: true
+    suggestedAction: "OpenClaw gateway not responding; check `clawops logs` for issues."
+  - id: op.ssh_connect_failed
+    class: OperationalError
+    retryable: true
+    suggestedAction: "SSH connection failed; check key path, host availability, and security group."
+
+  # Cancellation
+  - id: op.cancelled
+    class: CancelledError
+    suggestedAction: "Operation cancelled by user."
+
+# Sensitive field patterns for redaction (R21).
+# Used by both pino logger config and src/mcp/audit.ts.
+redaction:
+  patterns:
+    - authorization
+    - "*.authorization"
+    - token
+    - "*.token"
+    - password
+    - "*.password"
+    - secret
+    - "*.secret"
+    - connectionString
+    - "*.connectionString"
+    - aws_access_key_id
+    - "*.aws_access_key_id"
+    - aws_secret_access_key
+    - "*.aws_secret_access_key"
+    - GOOGLE_APPLICATION_CREDENTIALS
+    - AZURE_CLIENT_SECRET
+    - HCLOUD_TOKEN
+    - DO_API_TOKEN
+    - CLOUDFLARE_API_TOKEN
+  censor: "***"