@0cloud/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# 0cloud CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The service client for 0cloud. Use the same workspace from your terminal, scripts or coding agent. Requires Node.js 24 or later. The separate `0` engine is not required or installed.
+
+```sh
+npm install -g @0cloud/cli
+0cloud auth login
+0cloud codebases list
+0cloud capabilities
+```
+
+For a local deployment, use `0cloud auth login --dashboard http://localhost:3001`.
+Login opens the dashboard and saves the selected workspace's scoped token in
+`~/.0cloud/credentials.json` with owner-only permissions. It never changes `0`
+credentials. `ZERO_CLOUD_TOKEN`, `ZERO_CLOUD_ORG` and `ZERO_CLOUD_ENDPOINT` support
+CI. `--endpoint` and `--org` override the saved service and workspace.
+
+## Choose the work
+
+| Task | Command |
+| --- | --- |
+| Analyze local source without executing it | `0cloud scan ./src` |
+| Deeper source-only analysis | `0cloud scan ./src --whitebox --focus "Account access"` |
+| Inspect connected codebases | `0cloud codebases list` or `codebases show <repo-or-id>` |
+| Check saved scope and readiness | `0cloud tests readiness <repo-or-id>` |
+| Start a saved-codebase security test | `0cloud tests start <repo-or-id> --idempotency-key <uuid>` |
+| Read PR Security history | `0cloud reviews list` |
+| Inspect progress or results | `0cloud runs show <id>` or `runs report <id>` |
+| Inspect recorded problems | `0cloud findings list` or `findings show <id>` |
+| Read Memory rules and feedback | `0cloud memory list` |
+| Check funding readiness | `0cloud usage status` |
+
+**Security tests** is the dashboard workflow name. `tests` is the corresponding
+CLI command. Existing `pentests start` commands remain compatible. `scan` is
+source-only analysis, with results that do not establish reproduction or verified
+repairs. Opening configuration or checking readiness does not start work.
+
+## Source analysis
+
+```sh
+0cloud scan ./src
+0cloud scan https://github.com/owner/repository
+0cloud scan ./src --whitebox --focus "Authorization and tenant isolation"
+```
+
+Uploads exclude symlinks, `.env` files, dependency/build directories, invalid
+UTF-8 and common binary formats. Limits: 300 files, 400 KB per file and 8 MB total.
+Excluded paths are reported on stderr; exceeding total limits fails rather than
+silently returning a partial submission. Review the files you select before upload.
+
+`--whitebox` uses `/api/whitebox-scan`; `--focus` requires it. Repository URL
+support depends on deployment configuration. Funded source-analysis deployments
+can require file uploads; a rejected URL is reported as an error without a fallback.
+
+For deployments with queued source operations enabled:
+
+```sh
+0cloud source-scans start <repository-uuid> --commit <full-40-character-sha> \
+  --operation whitebox-scan --idempotency-key <uuid>
+0cloud source-scans list --repository <repository-uuid>
+0cloud source-scans show <job-id>
+0cloud source-scans wait <job-id>
+0cloud source-scans cancel <job-id>
+```
+
+Queued source jobs use their own IDs and `source-scans` commands. Managed
+executions use `runs`. A `recovery_required` result is a failure requiring usage
+reconciliation, never a reason to resubmit automatically. Deployment feature
+flags, authority and operation limits remain server-controlled.
+
+## Codebases and security tests
+
+```sh
+0cloud codebases show owner/repository
+0cloud codebases configure owner/repository --file plan.json
+0cloud tests readiness owner/repository
+0cloud tests start owner/repository --idempotency-key <uuid>
+0cloud runs wait <run-id>
+0cloud runs report <run-id>
+```
+
+`configure` reads JSON containing `plan` and optional `enableSchedule`. It saves
+against the server's current revision and source revision. Inspect `codebases
+show` and the proposed plan before saving. It never starts a test. Changing a
+schedule or publication policy requires your explicit decision.
+
+`codebases enroll <repository-uuid>` enrolls a repository already available
+through the workspace's GitHub connection; inspect its saved trigger policy first.
+GitHub connection and new-install consent remain browser flows.
+
+Start uses the saved scope, budget and publication policy. The CLI prints an
+attempt key to stderr before submission. Save it. If a response is lost, inspect
+the recorded runs and reuse the same key for the same attempt. Do not generate a
+new key or replay automatically when execution or usage is uncertain. A start
+response is admission evidence, not proof of a completed test.
+
+## History and review
+
+```sh
+0cloud runs list --status failed --limit 20 --offset 20
+0cloud runs events <run-id> --limit 100 --offset 100
+0cloud findings list --scan-id <run-id> --status pending --limit 20 --offset 20
+0cloud findings triage <finding-id> --status unsure --reason "Needs reproduction evidence"
+0cloud reviews list --days 0 --repository <repository-uuid>
+```
+
+PR history defaults to all time; `--days` accepts 0, 7, 30 or 90. Use `--cursor`
+with the JSON cursor returned by the API, or `--page` for its existing page API.
+Runs, findings and events support `--limit` and `--offset`. Review decisions do
+not establish reproduction or a verified repair. PR execution follows saved
+repository triggers; manual review dispatch and GitHub delivery are not added
+by this CLI release.
+
+## Memory and usage
+
+```sh
+0cloud memory list
+0cloud memory list --repository <repository-uuid>
+0cloud memory add "Check tenant ownership before reading records" --revision <revision>
+0cloud memory remove <workspace-memory-id> --revision <revision>
+0cloud usage status
+0cloud usage models
+```
+
+Memory writes manage explicit workspace rules. Use the exact revision and rule
+ID returned by the API. Conflicts are reported without automatic overwrite.
+The repository filter scopes reads; it does not change the scope of new rules.
+Observed facts and feedback remain distinct from approved rules. Generated
+Knowledge documents do not yet have a dedicated public CLI API.
+
+Usage commands only read account admission and the model catalog. They cannot
+purchase usage, change caps, consent to paid usage or waive unresolved charges.
+Required token scopes and workspace roles are enforced by the server.
+
+## Other commands
+
+- `dependencies list`, `dependencies scan`: read or refresh dependency checks.
+- `dependencies fix <dependency-id> <finding-id>`: explicitly open an upgrade PR; never merge it.
+- `auth status`, `auth logout`: inspect or remove this CLI's saved credentials.
+- `api get/post/patch/delete <relative-path> [--file body.json]`: call an existing
+  workspace API with the same credentials and permissions. It does not expose
+  internal dashboard RPCs or bypass authorization.
+- `capabilities`: inspect the installed commands and known API gaps.
+
+Website/app target creation, authorization and test start need a public API
+matching the dashboard flow. They are not disguised as codebase tests. Team,
+integration and payment administration remain dashboard workflows.
+
+## Output and errors
+
+Results are JSON on stdout. Diagnostics and attempt keys go to stderr. Exit codes:
+0 success, 1 invalid input/configuration or wait timeout, 2 API/network failure or
+an unsuccessful terminal run. Source allow/review/block verdicts are data, not
+transport failures. A wait timeout does not cancel the job. The client never
+retries writes automatically. Unavailable routes fail visibly.
+
+## Development
+
+```sh
+pnpm --filter @0cloud/cli build
+pnpm --filter @0cloud/cli test
+node packages/0cloud-cli/dist/public/public-cli.js --help
+```
+
+The npm allowlist includes only `dist/public` and this README. Operator commands
+in `src/cli.ts` and `OPERATOR.md` are excluded from the public entry point.

package/dist/public/commands/auth.js

@@ -0,0 +1,114 @@
+// `0cloud auth <subcommand>` — dashboard browser login for CLI tokens.
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { apiEndpointFromDashboard, credentialsPath, DEFAULT_DASHBOARD_URL, DEFAULT_ENDPOINT, deleteCredentialsFile, readCredentialsFile, writeCredentialsFile, } from "../config.js";
+import { printJson } from "../format.js";
+import { UserError } from "../errors.js";
+export async function runAuthLogin(opts) {
+    const dashboardUrl = stripTrailingSlash(opts.dashboard ??
+        process.env.ZERO_CLOUD_DASHBOARD_URL ??
+        DEFAULT_DASHBOARD_URL);
+    const endpoint = stripTrailingSlash(opts.endpoint ?? process.env.ZERO_CLOUD_ENDPOINT ?? apiEndpointFromDashboard(dashboardUrl));
+    const sessionId = randomBytes(24).toString("base64url");
+    const loginUrl = `${dashboardUrl}/cli-auth?session=${encodeURIComponent(sessionId)}`;
+    process.stdout.write(`Open this URL to authorize 0cloud:\n${loginUrl}\n`);
+    if (opts.open !== false)
+        openBrowser(loginUrl);
+    const intervalMs = positiveInt(opts.pollInterval ?? 2, "--poll-interval") * 1000;
+    const timeoutMs = positiveInt(opts.timeout ?? 600, "--timeout") * 1000;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const result = await pollSession(dashboardUrl, sessionId);
+        if (result.status === "ready") {
+            if (!result.org_id) {
+                throw new UserError("Dashboard returned a token without org_id; cannot configure tenant scope.");
+            }
+            await writeCredentialsFile({
+                token: result.token,
+                orgId: result.org_id,
+                endpoint,
+                dashboardUrl,
+                scopes: result.scopes,
+                createdAt: new Date().toISOString(),
+            });
+            process.stdout.write(`Authenticated. Wrote ${credentialsPath()}\n`);
+            process.stdout.write(`  org_id: ${result.org_id}\n`);
+            return;
+        }
+        if (result.status === "expired") {
+            throw new UserError("CLI auth session expired. Run `0cloud auth login` again.");
+        }
+        await sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+    }
+    throw new UserError(`Timed out waiting for browser authorization after ${Math.floor(timeoutMs / 1000)}s.`);
+}
+export async function runAuthStatus(opts = {}) {
+    const creds = await readCredentialsFile();
+    if (opts.json) {
+        printJson({
+            authenticated: creds !== null,
+            credentials_file: credentialsPath(),
+            credentials: creds
+                ? {
+                    orgId: creds.orgId,
+                    orgSlug: creds.orgSlug ?? null,
+                    endpoint: creds.endpoint ?? null,
+                    dashboardUrl: creds.dashboardUrl ?? null,
+                    scopes: creds.scopes ?? [],
+                    createdAt: creds.createdAt ?? null,
+                }
+                : null,
+        });
+        return;
+    }
+    if (!creds) {
+        process.stdout.write(`Not authenticated. Run \`0cloud auth login\`.\n`);
+        return;
+    }
+    process.stdout.write(`Authenticated\n  credentials: ${credentialsPath()}\n  org_id:      ${creds.orgId}\n  endpoint:    ${creds.endpoint ?? DEFAULT_ENDPOINT}\n  dashboard:   ${creds.dashboardUrl ?? DEFAULT_DASHBOARD_URL}\n`);
+}
+export async function runAuthLogout() {
+    const deleted = await deleteCredentialsFile();
+    process.stdout.write(deleted ? `Deleted ${credentialsPath()}\n` : "No credentials file found.\n");
+}
+async function pollSession(dashboardUrl, sessionId) {
+    const url = `${dashboardUrl}/cli-auth/sessions/${encodeURIComponent(sessionId)}`;
+    const response = await fetch(url, {
+        headers: { Accept: "application/json" },
+    });
+    if (response.status === 404)
+        return { status: "pending" };
+    if (!response.ok) {
+        throw new UserError(`CLI auth poll failed: HTTP ${response.status}`);
+    }
+    const parsed = (await response.json());
+    if (parsed.status !== "pending" &&
+        parsed.status !== "expired" &&
+        parsed.status !== "ready") {
+        throw new UserError("CLI auth poll returned an unknown status.");
+    }
+    return parsed;
+}
+function openBrowser(url) {
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => undefined);
+    child.unref();
+}
+function positiveInt(value, name) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new UserError(`${name} must be a positive integer.`);
+    }
+    return value;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function stripTrailingSlash(value) {
+    return value.endsWith("/") ? value.slice(0, -1) : value;
+}

package/dist/public/config.js

@@ -0,0 +1,218 @@
+// Config-file + env resolution for 0cloud.
+//
+// Config layout:
+//   ~/.0cloud/config.json — { endpoint, orgId, orgSlug? }
+//   ~/.0cloud/credentials.json — dashboard-minted CLI token
+//   env ZERO_CLOUD_OPERATOR_TOKEN — operator bearer override
+//   env ZERO_CLOUD_TOKEN          — CLI token override
+//   env ZERO_CLOUD_ENDPOINT       — override endpoint
+//   env ZERO_CLOUD_ORG            — override org slug
+//
+// Precedence (high to low) for endpoint + org:
+//   1. command-line flag (--endpoint, --org)
+//   2. env var
+//   3. config file
+//   4. built-in default (endpoint only — org has no default)
+//
+// Long-lived CLI tokens live in credentials.json with mode-0600. The
+// operator token remains env-only.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { UserError } from "./errors.js";
+let configFileReader = (p) => fs.readFile(p, "utf8");
+export function _setConfigFileReader(reader) {
+    configFileReader = reader ?? ((p) => fs.readFile(p, "utf8"));
+}
+// The orchestrator API is served at cloud.0.security/api (Traefik routes
+// /api/* → strip-api → orchestrator). `api.0.security` has no DNS record,
+// so it must NOT be a default (#508). The dashboard (auth, cli-auth,
+// health) is the bare cloud.0.security host.
+//
+// Canonical-host change 2026-08-08: 0.security replaced the former
+// 0sec.ai brand domain. A redirect default is broken for this CLI: native fetch drops the
+// Authorization header on the cross-origin redirect hop, so every
+// authenticated request 401s with "missing bearer token". The defaults
+// must point at the canonical host directly.
+export const DEFAULT_ENDPOINT = "https://cloud.0.security/api";
+export const DEFAULT_DASHBOARD_URL = "https://cloud.0.security";
+// Dev environment: the dashboard + orchestrator HMR served from the devbox
+// over Tailscale at dev.cloud.0.security (the website dev host is
+// dev.0.security). Reachable only on the tailnet. `--dev` selects these so a
+// founder does not have to remember the hostnames or export env overrides.
+export const DEV_ENDPOINT = "https://dev.cloud.0.security/api";
+export const DEV_DASHBOARD_URL = "https://dev.cloud.0.security";
+/**
+ * Derive the orchestrator API base URL from a dashboard host. 0
+ * only knows the dashboard host (cloud.0.security); the 0cloud API lives
+ * under `/api` on that same host. Idempotent if `/api` is already present.
+ */
+export function apiEndpointFromDashboard(dashboardHost) {
+    const trimmed = dashboardHost.replace(/\/+$/, "");
+    return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
+}
+export function configDir() {
+    return process.env.ZERO_CLOUD_CONFIG_DIR ?? path.join(os.homedir(), ".0cloud");
+}
+export function configPath() {
+    return path.join(configDir(), "config.json");
+}
+export function credentialsPath() {
+    return path.join(configDir(), "credentials.json");
+}
+export async function readConfigFile() {
+    try {
+        const raw = await configFileReader(configPath());
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            "endpoint" in parsed &&
+            "orgId" in parsed &&
+            typeof parsed.endpoint === "string" &&
+            typeof parsed.orgId === "string") {
+            const cf = parsed;
+            return {
+                endpoint: cf.endpoint,
+                orgId: cf.orgId,
+                orgSlug: typeof cf.orgSlug === "string" ? cf.orgSlug : undefined,
+            };
+        }
+        return null;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export async function writeConfigFile(cfg) {
+    await fs.mkdir(configDir(), { recursive: true });
+    await fs.writeFile(configPath(), JSON.stringify(cfg, null, 2) + "\n", {
+        mode: 0o600,
+    });
+}
+export async function readCredentialsFile() {
+    try {
+        const raw = await configFileReader(credentialsPath());
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            typeof parsed.token === "string" &&
+            typeof parsed.orgId === "string") {
+            const c = parsed;
+            return {
+                token: c.token,
+                orgId: c.orgId,
+                orgSlug: typeof c.orgSlug === "string" ? c.orgSlug : undefined,
+                endpoint: typeof c.endpoint === "string" ? c.endpoint : undefined,
+                dashboardUrl: typeof c.dashboardUrl === "string" ? c.dashboardUrl : undefined,
+                scopes: Array.isArray(c.scopes)
+                    ? c.scopes.filter((s) => typeof s === "string")
+                    : undefined,
+                createdAt: typeof c.createdAt === "string" ? c.createdAt : undefined,
+            };
+        }
+        return null;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}
+export async function writeCredentialsFile(creds) {
+    await fs.mkdir(configDir(), { recursive: true });
+    await fs.writeFile(credentialsPath(), JSON.stringify(creds, null, 2) + "\n", {
+        mode: 0o600,
+    });
+    await fs.chmod(credentialsPath(), 0o600);
+}
+export async function deleteCredentialsFile() {
+    try {
+        await fs.unlink(credentialsPath());
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+const ORG_ID_RE = /^[A-Za-z0-9_-]{16,64}$/;
+/**
+ * Resolve the runtime context (endpoint, org id, token) for a command
+ * invocation. Throws UserError with a helpful message when any required
+ * piece is missing — the command handler propagates that up to cli.ts
+ * which maps it to exit 1.
+ */
+export async function resolveContext(overrides, env = process.env, options = {}) {
+    const requireOrg = options.requireOrg ?? true;
+    const cfgFile = await readConfigFile();
+    const credsFile = await readCredentialsFile();
+    const token = env.ZERO_CLOUD_OPERATOR_TOKEN ??
+        env.ZERO_CLOUD_TOKEN ??
+        credsFile?.token;
+    if (!token || token.trim() === "") {
+        throw new UserError("No cloud token found. Run `0cloud auth login`, set ZERO_CLOUD_TOKEN, or export ZERO_CLOUD_OPERATOR_TOKEN.");
+    }
+    const endpoint = overrides.endpoint ??
+        env.ZERO_CLOUD_ENDPOINT ??
+        cfgFile?.endpoint ??
+        credsFile?.endpoint ??
+        DEFAULT_ENDPOINT;
+    if (!requireOrg) {
+        return {
+            endpoint: stripTrailingSlash(endpoint),
+            token,
+            verbose: overrides.verbose === true,
+        };
+    }
+    // --org / env / config-file. We accept either an id (header-ready)
+    // or a slug (display-only) at this layer. `0cloud orgs list` can
+    // bootstrap ids, but tenant-scoped commands still need a header-ready
+    // id or a config-file slug -> id mapping.
+    const rawOrg = overrides.org ??
+        env.ZERO_CLOUD_ORG ??
+        cfgFile?.orgSlug ??
+        cfgFile?.orgId ??
+        credsFile?.orgSlug ??
+        credsFile?.orgId;
+    if (!rawOrg) {
+        throw new UserError("No org specified. Set --org <id-or-slug>, ZERO_CLOUD_ORG, or run `0cloud config init`.");
+    }
+    let orgId;
+    let orgSlug;
+    if (ORG_ID_RE.test(rawOrg)) {
+        // Header-ready id.
+        orgId = rawOrg;
+        orgSlug = cfgFile?.orgSlug ?? credsFile?.orgSlug;
+    }
+    else {
+        // Looks like a slug. If the config file maps it to an id, use the
+        // id; otherwise refuse rather than send a slug the orchestrator
+        // will silently re-attribute to the operator org (see the memory
+        // note at reference_operator_token_org_scoping.md).
+        if (cfgFile && cfgFile.orgSlug === rawOrg) {
+            orgId = cfgFile.orgId;
+            orgSlug = cfgFile.orgSlug;
+        }
+        else if (credsFile && credsFile.orgSlug === rawOrg) {
+            orgId = credsFile.orgId;
+            orgSlug = credsFile.orgSlug;
+        }
+        else {
+            throw new UserError(`Org slug "${rawOrg}" is not mapped to an id. Pass the opaque org id via --org / ZERO_CLOUD_ORG, run \`0cloud auth login\`, or set { "orgSlug": "${rawOrg}", "orgId": "..." } in ~/.0cloud/config.json.`);
+        }
+    }
+    return {
+        endpoint: stripTrailingSlash(endpoint),
+        orgId,
+        orgSlug,
+        token,
+        verbose: overrides.verbose === true,
+    };
+}
+function stripTrailingSlash(s) {
+    return s.endsWith("/") ? s.slice(0, -1) : s;
+}

package/dist/public/customer.js

@@ -0,0 +1,120 @@
+import { randomUUID } from "node:crypto";
+import { readdir, lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveContext } from "./config.js";
+import { request } from "./http.js";
+import { UserError } from "./errors.js";
+export function dashboardApiContext(ctx) {
+    return { ...ctx, endpoint: ctx.endpoint.replace(/\/orchestrator\/?$/, "") };
+}
+export async function customerRequest(opts, route, method = "GET", body) {
+    if (!/^\/[a-zA-Z0-9]/.test(route) || route.includes("\\") || route.includes("#") || /(^|\/)\.\.(\/|$)/.test(decodeURIComponent(route))) {
+        throw new UserError("Use a relative API path, for example /scan or /project-setup.");
+    }
+    const ctx = dashboardApiContext(await resolveContext(opts));
+    return request(ctx, route, { method, body });
+}
+const SKIP = new Set([".git", "node_modules", "vendor", "dist", "build", ".next", "target", "__pycache__", ".env", ".env.local"]);
+const BINARY = /\.(png|jpe?g|gif|webp|ico|pdf|zip|gz|tar|wasm|woff2?|ttf|eot|mp[34]|mov|exe|dll|so|dylib|bin)$/i;
+const MAX_FILES = 300;
+const MAX_FILE_BYTES = 400_000;
+const MAX_TOTAL_BYTES = 8_000_000;
+/** Upload source as data. Never execute it or follow filesystem symlinks. */
+export async function readSubmission(input) {
+    const root = path.resolve(input);
+    const info = await lstat(root).catch(() => { throw new UserError(`File or folder not found: ${input}`); });
+    if (info.isSymbolicLink())
+        throw new UserError("Choose a file or folder, not a symlink.");
+    const files = [];
+    let skipped = 0;
+    let bytes = 0;
+    async function walk(file) {
+        const name = path.basename(file);
+        if (SKIP.has(name) || name.startsWith(".env.")) {
+            skipped++;
+            return;
+        }
+        const stat = await lstat(file);
+        if (stat.isSymbolicLink()) {
+            skipped++;
+            return;
+        }
+        if (stat.isDirectory()) {
+            for (const entry of (await readdir(file)).sort())
+                await walk(path.join(file, entry));
+        }
+        else if (stat.isFile()) {
+            if (BINARY.test(name) || stat.size > MAX_FILE_BYTES) {
+                skipped++;
+                return;
+            }
+            if (files.length >= MAX_FILES || bytes + stat.size > MAX_TOTAL_BYTES) {
+                throw new UserError("Submission exceeds 300 files or 8 MB. Select a smaller folder.");
+            }
+            const buffer = await readFile(file);
+            if (buffer.includes(0)) {
+                skipped++;
+                return;
+            }
+            let content;
+            try {
+                content = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+            }
+            catch {
+                skipped++;
+                return;
+            }
+            files.push({ path: info.isDirectory() ? path.relative(root, file).split(path.sep).join("/") : name, content });
+            bytes += buffer.length;
+        }
+    }
+    await walk(root);
+    if (!files.length)
+        throw new UserError("No source files to scan.");
+    return { files, skipped };
+}
+export async function scanSubmission(input, opts, options = {}) {
+    if (options.focus && !options.whitebox)
+        throw new UserError("--focus requires --whitebox.");
+    const route = options.whitebox ? "/whitebox-scan" : "/scan";
+    const focus = options.focus ? { focus: options.focus } : {};
+    if (/^https:\/\//i.test(input))
+        return customerRequest(opts, route, "POST", options.whitebox ? { input, ...focus } : { repo_url: input });
+    const { files, skipped } = await readSubmission(input);
+    if (skipped)
+        process.stderr.write(`Skipped ${skipped} binary, generated or excluded paths.\n`);
+    return customerRequest(opts, route, "POST", { files, ...focus });
+}
+export async function readCodebase(target, opts) {
+    const field = /^[0-9a-f-]{36}$/i.test(target) ? "repository_id" : "target";
+    return await customerRequest(opts, `/project-setup?${field}=${encodeURIComponent(target)}`);
+}
+export async function startPentest(target, opts, idempotencyKey = randomUUID()) {
+    if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(idempotencyKey))
+        throw new UserError("Idempotency key must be a UUID.");
+    process.stderr.write(`Attempt key: ${idempotencyKey}. Reuse it for the same request after a connection failure; do not automatically resubmit.\n`);
+    const record = await readCodebase(target, opts);
+    if (!record.readiness.canStart)
+        throw new UserError(record.readiness.reason || "Save and approve the codebase configuration before starting a pentest.");
+    return customerRequest(opts, "/project-setup", "POST", {
+        action: "start", repositoryId: record.repository.id,
+        expectedRevision: record.revision, idempotencyKey,
+    });
+}
+export async function saveCodebase(target, file, opts) {
+    const record = await readCodebase(target, opts);
+    let input;
+    try {
+        input = JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        throw new UserError("Configuration must be a JSON file containing plan and optional enableSchedule.");
+    }
+    if (!input || typeof input !== "object" || !input.plan)
+        throw new UserError("Configuration must contain plan.");
+    return customerRequest(opts, "/project-setup", "POST", {
+        action: "save", repositoryId: record.repository.id, expectedRevision: record.revision,
+        sourceRevision: record.repository.sourceRevision, plan: input.plan,
+        ...(input.enableSchedule !== undefined ? { enableSchedule: input.enableSchedule } : {}),
+    });
+}

package/dist/public/errors.js

@@ -0,0 +1,30 @@
+// Exit-code discipline for 0cloud.
+//
+// 0 = success
+// 1 = user error (bad flags, missing token, missing org, config error)
+// 2 = server error (4xx/5xx from the API, network error)
+//
+// The CLI is meant to be safe to wrap in shell scripts and agent
+// tool-calls, so the exit code is the single contract for "did this
+// work?". Errors that violate the contract (e.g. an uncaught throw
+// in a command handler) are caught at the top of cli.ts and mapped
+// to exit 2 with a generic message so we never leak a stack trace
+// to stdout / stderr.
+export class UserError extends Error {
+    exitCode = 1;
+    constructor(message) {
+        super(message);
+        this.name = "UserError";
+    }
+}
+export class ServerError extends Error {
+    exitCode = 2;
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "ServerError";
+        this.status = status;
+        this.body = body;
+    }
+}

package/dist/public/format.js

@@ -0,0 +1,71 @@
+// Tiny built-in table formatter — no cli-table / cli-truncate deps.
+//
+// The CLI's whole job is to be fast to install + boring to maintain;
+// pulling in a chalk + cli-table stack adds dependencies that the
+// `pnpm audit` surface has to track forever. String-padding is fine
+// for the row counts we render (scans/findings lists cap at ~500).
+//
+// Color is intentionally off. The CLI is consumed by agents and by
+// scripts piping to other tools; ANSI escapes break shell pipelines
+// silently. If we add color later, gate it behind `--color` and
+// auto-disable when stdout is not a TTY.
+export function formatTable(rows, columns) {
+    if (rows.length === 0)
+        return "(no rows)\n";
+    const stringRows = rows.map((row) => columns.map((col) => {
+        const v = col.value(row);
+        const s = v == null ? "" : String(v);
+        return truncate(s, col.maxWidth);
+    }));
+    const widths = columns.map((col, i) => {
+        const headerWidth = col.header.length;
+        const maxCell = stringRows.reduce((acc, r) => Math.max(acc, (r[i] ?? "").length), 0);
+        return Math.max(headerWidth, maxCell);
+    });
+    const headerLine = columns
+        .map((col, i) => col.header.padEnd(widths[i] ?? col.header.length))
+        .join("  ");
+    const separator = widths.map((w) => "-".repeat(w)).join("  ");
+    const dataLines = stringRows.map((r) => r.map((cell, i) => cell.padEnd(widths[i] ?? cell.length)).join("  "));
+    return [headerLine, separator, ...dataLines].join("\n") + "\n";
+}
+function truncate(s, max) {
+    if (max === undefined || s.length <= max)
+        return s;
+    if (max <= 1)
+        return s.slice(0, max);
+    return s.slice(0, max - 1) + "…";
+}
+/**
+ * Format a Date / ISO string into a compact relative form
+ * ("2m ago", "5h ago", "3d ago"). Falls back to the raw ISO string
+ * for values older than ~30 days so the caller can read the date.
+ */
+export function relativeTime(value, now = Date.now()) {
+    if (!value)
+        return "";
+    const t = Date.parse(value);
+    if (Number.isNaN(t))
+        return value;
+    const deltaSec = Math.max(0, Math.floor((now - t) / 1000));
+    if (deltaSec < 60)
+        return `${deltaSec}s ago`;
+    const deltaMin = Math.floor(deltaSec / 60);
+    if (deltaMin < 60)
+        return `${deltaMin}m ago`;
+    const deltaHr = Math.floor(deltaMin / 60);
+    if (deltaHr < 48)
+        return `${deltaHr}h ago`;
+    const deltaDay = Math.floor(deltaHr / 24);
+    if (deltaDay < 30)
+        return `${deltaDay}d ago`;
+    return value.slice(0, 10);
+}
+/**
+ * Pretty-print an arbitrary JSON value to stdout with 2-space indent.
+ * Used by every command's --json branch. Centralised here so we can
+ * later add a `--compact` / `--ndjson` mode in one place.
+ */
+export function printJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}

package/dist/public/http.js

@@ -0,0 +1,99 @@
+// Thin HTTP wrapper around native fetch.
+//
+// Adds:
+//   - Authorization: Bearer <operator token>
+//   - X-0-Org-Id: <orgId> for tenant-scoped requests (see the
+//     org-scoping memory note; without this the orchestrator defaults
+//     to the operator org and tenant scan / finding rows become
+//     invisible in /<slug>/scans)
+//   - User-Agent: 0cloud/<version>
+//   - JSON request body + Content-Type handling
+//   - Optional verbose log line (method + url + status — NEVER the
+//     auth header)
+//   - Maps non-2xx responses to a typed ServerError; uses 2xx body as
+//     `unknown` so callers narrow with a type guard.
+//
+// Native fetch is used directly — Node 24 ships a stable
+// implementation (the orchestrator pins ">=24.0.0" in its
+// package.json `engines`, this package matches).
+import { ServerError } from "./errors.js";
+// Hardcoded — kept in sync with package.json manually. The dist
+// build doesn't have a `process.env.npm_package_version` baked in
+// when run as a global bin, so we ship a constant.
+export const USER_AGENT_VERSION = "0.1.0";
+export async function request(ctx, pathAndQuery, options = {}) {
+    const method = options.method ?? "GET";
+    const url = buildUrl(ctx.endpoint, pathAndQuery, options.query);
+    const headers = {
+        Authorization: `Bearer ${ctx.token}`,
+        "User-Agent": `0cloud/${USER_AGENT_VERSION}`,
+        Accept: "application/json",
+    };
+    if (!options.omitOrgHeader && ctx.orgId) {
+        headers["X-0-Org-Id"] = ctx.orgId;
+    }
+    let body;
+    if (options.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        body = JSON.stringify(options.body);
+    }
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const stderr = options.stderr ?? process.stderr;
+    const startedAt = Date.now();
+    const response = await fetchImpl(url, { method, headers, body, redirect: "error", signal: AbortSignal.timeout(300_000) });
+    const durationMs = Date.now() - startedAt;
+    if (ctx.verbose) {
+        // NEVER log the Authorization header. Method + url + status +
+        // duration is enough to debug routing / org scoping without
+        // leaking the operator bearer into a shared terminal.
+        stderr.write(`[0cloud] ${method} ${url} -> ${response.status} (${durationMs}ms)\n`);
+    }
+    // Try to parse the body as JSON. Some routes (e.g. the artifact-
+    // bundle zip stream — not currently called by the CLI) return
+    // non-JSON; we don't handle that here. All JSON-returning routes
+    // emit either a 2xx object or an `{ error: string, ... }` 4xx/5xx.
+    const text = await response.text();
+    let parsed = null;
+    if (text.length > 0) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // Non-JSON body. Fall through with `parsed = null`; the error
+            // path below carries `text` as a fallback.
+            parsed = text;
+        }
+    }
+    if (!response.ok) {
+        const message = extractErrorMessage(parsed, text, response.status);
+        throw new ServerError(message, response.status, parsed);
+    }
+    return parsed;
+}
+function buildUrl(endpoint, pathAndQuery, query) {
+    const base = endpoint.endsWith("/") ? endpoint.slice(0, -1) : endpoint;
+    const suffix = pathAndQuery.startsWith("/") ? pathAndQuery : `/${pathAndQuery}`;
+    const url = new URL(`${base}${suffix}`);
+    if (query) {
+        for (const [k, v] of Object.entries(query)) {
+            if (v === undefined)
+                continue;
+            url.searchParams.set(k, String(v));
+        }
+    }
+    return url.toString();
+}
+function extractErrorMessage(parsed, rawText, status) {
+    if (parsed && typeof parsed === "object") {
+        const obj = parsed;
+        if (typeof obj.message === "string" && obj.message.length > 0) {
+            return `${status} ${obj.message}`;
+        }
+        if (typeof obj.error === "string" && obj.error.length > 0) {
+            return `${status} ${obj.error}`;
+        }
+    }
+    if (rawText.length > 0)
+        return `${status} ${rawText.slice(0, 200)}`;
+    return `HTTP ${status}`;
+}

package/dist/public/public-cli.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { Command, CommanderError, Option } from "commander";
+import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { runAuthLogin, runAuthLogout, runAuthStatus } from "./commands/auth.js";
+import { resolveContext } from "./config.js";
+import { request } from "./http.js";
+import { UserError } from "./errors.js";
+import { customerRequest, readCodebase, saveCodebase, scanSubmission, startPentest } from "./customer.js";
+import { registerWorkflowCommands } from "./workflow-commands.js";
+import { USER_AGENT_VERSION } from "./http.js";
+function output(value) { process.stdout.write(JSON.stringify(value, null, 2) + "\n"); }
+function positive(value) {
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 1)
+        throw new UserError("Expected a positive integer.");
+    return n;
+}
+function nonnegative(value) {
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 0)
+        throw new UserError("Expected a nonnegative integer.");
+    return n;
+}
+function context(cmd) { return cmd.optsWithGlobals(); }
+const terminal = new Set(["complete", "failed", "cancelled", "cost_exceeded", "capacity_exceeded"]);
+/** Public client only. Internal research/disclosure/operator commands stay private. */
+export function buildPublicProgram() {
+    const p = new Command().name("0cloud").version(USER_AGENT_VERSION)
+        .description("Security tests, source analysis and workspace actions through the 0cloud API. Results are JSON.")
+        .option("--endpoint <url>", "API base URL; defaults to your saved login")
+        .option("--org <id>", "Workspace ID; defaults to your saved login")
+        .option("--json", "Output JSON (default)")
+        .option("-v, --verbose", "Log request method, URL and status to stderr");
+    const auth = p.command("auth").description("Sign in and manage this CLI's credentials");
+    auth.command("login").option("--dashboard <url>", "Dashboard URL")
+        .option("--no-open", "Print the login URL without opening it")
+        .option("--timeout <seconds>", "Login timeout", positive, 600)
+        .option("--poll-interval <seconds>", "Login polling interval", positive, 2)
+        .action(async (o, cmd) => runAuthLogin({ ...context(cmd), ...o }));
+    auth.command("status").action(async (_o, cmd) => runAuthStatus({ json: true }));
+    auth.command("logout").action(runAuthLogout);
+    p.command("scan <file-folder-or-repo>").description("Analyze source without executing it")
+        .option("--whitebox", "Deeper source-only analysis, not an active security test")
+        .option("--focus <text>", "Focus instructions for whitebox analysis")
+        .action(async (input, o, cmd) => output(await scanSubmission(input, context(cmd), o)));
+    const codebases = p.command("codebases").description("Read and configure enrolled codebases");
+    codebases.command("list").action(async (_o, cmd) => output(await customerRequest(context(cmd), "/project-setup")));
+    codebases.command("show <repo-or-id>").action(async (target, _o, cmd) => output(await readCodebase(target, context(cmd))));
+    codebases.command("configure <repo-or-id>").requiredOption("--file <json>", "Plan JSON; schedules change only when enableSchedule is supplied")
+        .action(async (target, o, cmd) => output(await saveCodebase(target, o.file, context(cmd))));
+    codebases.command("enroll <repository-id>").description("Enroll a repository already available through the workspace GitHub connection")
+        .action(async (repositoryId, _o, cmd) => output(await customerRequest(context(cmd), "/project-setup", "POST", { action: "enroll", repositoryId })));
+    registerWorkflowCommands(p);
+    const pentests = p.command("pentests", { hidden: true }).description("Compatibility command; use tests start");
+    pentests.command("start <repo-or-id>").option("--idempotency-key <uuid>", "Reuse this key when retrying the same request")
+        .action(async (target, o, cmd) => output(await startPentest(target, context(cmd), o.idempotencyKey)));
+    const runs = p.command("runs").description("Read progress, results and cancellation for managed runs");
+    runs.command("list").option("--status <status>").option("--limit <n>", "Page size", positive, 20).option("--offset <n>", "Page offset", nonnegative, 0)
+        .action(async (o, cmd) => output(await request(await resolveContext(context(cmd)), "/scans", { query: { status: o.status, limit: o.limit, offset: o.offset } })));
+    runs.command("show <id>").action(async (id, _o, cmd) => output(await request(await resolveContext(context(cmd)), `/scans/${encodeURIComponent(id)}`)));
+    runs.command("events <id>").option("--limit <n>", "Event page size", positive, 100).option("--offset <n>", "Event offset", nonnegative, 0)
+        .action(async (id, o, cmd) => output(await request(await resolveContext(context(cmd)), `/scans/${encodeURIComponent(id)}/events`, { query: { limit: o.limit, offset: o.offset } })));
+    runs.command("cancel <id>").action(async (id, _o, cmd) => output(await request(await resolveContext(context(cmd)), `/scans/${encodeURIComponent(id)}/cancel`, { method: "POST" })));
+    runs.command("report <id>").action(async (id, _o, cmd) => output(await request(await resolveContext(context(cmd)), `/scans/${encodeURIComponent(id)}/artifact-bundle`)));
+    runs.command("wait <id>").option("--interval <seconds>", "Polling interval", positive, 5).option("--timeout <seconds>", "Timeout", positive, 1800)
+        .action(async (id, o, cmd) => {
+        const ctx = await resolveContext(context(cmd));
+        const end = Date.now() + o.timeout * 1000;
+        for (;;) {
+            const run = await request(ctx, `/scans/${encodeURIComponent(id)}`);
+            if (terminal.has(run.status)) {
+                output(run);
+                if (run.status !== "complete")
+                    process.exitCode = 2;
+                return;
+            }
+            if (Date.now() >= end)
+                throw new UserError("Timed out waiting. The run continues; use runs show or runs cancel.");
+            await delay(Math.min(o.interval * 1000, end - Date.now()));
+        }
+    });
+    const findings = p.command("findings").description("Read and review workspace findings");
+    findings.command("list").option("--status <status>", "Recorded review status").option("--category <category>").option("--scan-id <id>").option("--severity <severity>").option("--limit <n>", "Page size", positive, 20).option("--offset <n>", "Page offset", nonnegative, 0)
+        .action(async (o, cmd) => output(await request(await resolveContext(context(cmd)), "/findings", { query: { status: o.status, category: o.category, scan_id: o.scanId, severity: o.severity, limit: o.limit, offset: o.offset } })));
+    findings.command("show <id>").action(async (id, _o, cmd) => output(await request(await resolveContext(context(cmd)), `/findings/${encodeURIComponent(id)}`)));
+    findings.command("triage <id>").addOption(new Option("--status <status>").choices(["pending", "true_positive", "false_positive", "unsure", "reported", "wont_fix"]).makeOptionMandatory())
+        .requiredOption("--reason <text>", "Reason for the review decision")
+        .action(async (id, o, cmd) => output(await request(await resolveContext(context(cmd)), `/findings/${encodeURIComponent(id)}/triage`, { method: "POST", body: { triage_status: o.status, triage_notes: o.reason } })));
+    const deps = p.command("dependencies").description("Read and check dependencies of enrolled codebases");
+    deps.command("list").option("--limit <n>", "Page size (max 500)", positive, 20).option("--offset <n>", "Offset", value => { const n = Number(value); if (!Number.isSafeInteger(n) || n < 0)
+        throw new UserError("Offset must be a nonnegative integer."); return n; }, 0)
+        .action(async (o, cmd) => output(await customerRequest(context(cmd), `/dependencies?limit=${o.limit}&offset=${o.offset}`)));
+    deps.command("scan").action(async (_o, cmd) => output(await customerRequest(context(cmd), "/dependencies/scan", "POST")));
+    deps.command("fix <dependency-id> <finding-id>").description("Open an upgrade PR; does not merge it")
+        .action(async (dependencyId, findingId, _o, cmd) => output(await customerRequest(context(cmd), "/dependencies/fix", "POST", { dependencyId, findingId })));
+    const reviews = p.command("reviews").description("Read PR Security history; automatic reviews follow saved repository settings");
+    reviews.command("list").addOption(new Option("--days <n>", "History window; 0 means all time").choices(["0", "7", "30", "90"]).default("0")).option("--page <n>", "Page", positive, 1)
+        .option("--repository <id>", "Codebase UUID").option("--cursor <json>", "Next cursor returned by the API")
+        .action(async (o, cmd) => output(await customerRequest(context(cmd), `/reviews?${new URLSearchParams({ days: String(o.days), page: String(o.page), ...(o.repository ? { repository: o.repository } : {}), ...(o.cursor ? { cursor: o.cursor } : {}) })}`)));
+    const api = p.command("api").description("Call other workspace API actions using the same login");
+    for (const method of ["GET", "POST", "PATCH", "DELETE"]) {
+        api.command(`${method.toLowerCase()} <path>`).option("--file <json>", "JSON request body file")
+            .action(async (route, o, cmd) => {
+            let body;
+            if (o.file) {
+                try {
+                    body = JSON.parse(await readFile(o.file, "utf8"));
+                }
+                catch {
+                    throw new UserError("Request body must be a JSON file.");
+                }
+            }
+            if (method === "GET" && body !== undefined)
+                throw new UserError("GET requests cannot have a body.");
+            output(await customerRequest(context(cmd), route, method, body));
+        });
+    }
+    p.addHelpText("after", "\nStart here:\n  0cloud auth login\n  0cloud codebases list\n  0cloud tests readiness <codebase>\n  0cloud tests start <codebase> --idempotency-key <uuid>\n\nscan analyzes source; tests starts saved-codebase execution and honors its saved publication policy.\n");
+    p.command("capabilities").description("Print command and API coverage")
+        .action(() => output({ version: USER_AGENT_VERSION, commands: p.commands.map(c => c.name()),
+        workflows: { tests: "Saved-codebase security tests; pentests is a compatibility command", scan: "Immediate source-only analysis", sourceScans: "Queued exact-commit source analysis", memory: "Rules through the current Memory API", usage: "Read-only funding readiness and model catalog" },
+        pending: ["Website target setup and authorized test-start API parity", "Manual PR review dispatch", "Knowledge documents public API", "Team, integration and payment administration"],
+        note: "Server availability and workspace permissions determine which actions can run." }));
+    return p;
+}
+export async function runPublic(argv) {
+    process.exitCode = undefined;
+    const p = buildPublicProgram().exitOverride();
+    try {
+        await p.parseAsync(argv, { from: "user" });
+        return process.exitCode === 2 ? 2 : 0;
+    }
+    catch (err) {
+        if (err instanceof CommanderError)
+            return err.exitCode;
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        return err instanceof UserError ? 1 : 2;
+    }
+}
+const entry = process.argv[1] ? realpathSync(process.argv[1]) : null;
+if (entry === fileURLToPath(import.meta.url))
+    void runPublic(process.argv.slice(2)).then(code => { process.exitCode = code; });

package/dist/public/workflow-commands.js

@@ -0,0 +1,99 @@
+import { Option } from "commander";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { customerRequest, readCodebase, startPentest } from "./customer.js";
+import { resolveContext } from "./config.js";
+import { UserError } from "./errors.js";
+const output = (value) => { process.stdout.write(JSON.stringify(value, null, 2) + "\n"); };
+const context = (cmd) => cmd.optsWithGlobals();
+function integer(value) {
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 0)
+        throw new UserError("Expected a nonnegative integer.");
+    return n;
+}
+function positive(value) {
+    const n = integer(value);
+    if (!n)
+        throw new UserError("Expected a positive integer.");
+    return n;
+}
+function uuid(value) {
+    if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(value))
+        throw new UserError("Expected a UUID.");
+    return value.toLowerCase();
+}
+function sha(value) {
+    if (!/^[a-f0-9]{40}$/i.test(value))
+        throw new UserError("Use the full 40-character commit SHA.");
+    return value.toLowerCase();
+}
+/** Only existing public HTTP contracts. No dashboard RPCs or operator privileges. */
+export function registerWorkflowCommands(p) {
+    const tests = p.command("tests").description("Start security tests using an enrolled codebase's saved scope and budget");
+    tests.command("readiness <codebase>").description("Read configuration and admission readiness; does not start work")
+        .action(async (target, _o, cmd) => output(await readCodebase(target, context(cmd))));
+    tests.command("start <codebase>").option("--idempotency-key <uuid>", "Reuse for the same attempt; never automatically replay an unknown result", uuid)
+        .action(async (target, o, cmd) => output(await startPentest(target, context(cmd), o.idempotencyKey)));
+    const usage = p.command("usage").description("Read funding readiness and available inference models; never changes billing");
+    usage.command("status").action(async (_o, cmd) => output(await customerRequest(context(cmd), "/inference/account")));
+    usage.command("models").action(async (_o, cmd) => output(await customerRequest(context(cmd), "/inference/v1/models")));
+    const memory = p.command("memory").description("Read Memory and manage explicit rules with revision checks");
+    memory.command("list").option("--repository <uuid>", "Scope to a codebase", uuid)
+        .action(async (o, cmd) => output(await customerRequest(context(cmd), `/memory${o.repository ? `?repositoryId=${o.repository}` : ""}`)));
+    memory.command("add <text>").description("Add a workspace rule; does not alter repository execution policy").requiredOption("--revision <n>", "Revision returned by memory list", integer)
+        .action(async (text, o, cmd) => {
+        if (!text.trim() || text.trim().length > 1000)
+            throw new UserError("Use 1–1000 characters.");
+        output(await customerRequest(context(cmd), "/memory", "POST", { action: "add", text: text.trim(), expectedRevision: o.revision }));
+    });
+    memory.command("remove <id>").description("Remove an explicit workspace rule by its exact ID").requiredOption("--revision <n>", "Revision returned by memory list", integer)
+        .action(async (id, o, cmd) => output(await customerRequest(context(cmd), "/memory", "POST", { action: "remove", id, expectedRevision: o.revision })));
+    const source = p.command("source-scans").description("Queued source-only analysis pinned to an exact codebase commit; deployment must enable it");
+    source.command("list").option("--repository <uuid>", "Codebase UUID", uuid).option("--cursor <cursor>", "Next cursor returned by the API")
+        .action(async (o, cmd) => {
+        const ctx = await resolveContext(context(cmd));
+        const q = new URLSearchParams({ org_id: ctx.orgId, ...(o.repository ? { repository_id: o.repository } : {}), ...(o.cursor ? { cursor: o.cursor } : {}) });
+        output(await customerRequest(context(cmd), `/source-scans?${q}`));
+    });
+    source.command("start <repository-id>").requiredOption("--commit <sha>", "Full immutable commit SHA", sha)
+        .addOption(new Option("--operation <type>", "Source analysis method").choices(["scan", "whitebox-scan"]).default("scan"))
+        .option("--focus <text>", "Focus instructions, up to 4000 characters")
+        .option("--idempotency-key <uuid>", "Reuse for the same immutable submission", uuid)
+        .action(async (repository, o, cmd) => {
+        const repositoryId = uuid(repository);
+        if (o.focus?.length > 4000)
+            throw new UserError("Focus must be at most 4000 characters.");
+        const ctx = await resolveContext(context(cmd));
+        const idempotencyKey = o.idempotencyKey ?? randomUUID();
+        process.stderr.write(`Attempt key: ${idempotencyKey}. Reuse with the same repository, commit, operation and focus after a connection failure.\n`);
+        output(await customerRequest(context(cmd), "/source-scans", "POST", { orgId: ctx.orgId, repositoryId, commitSha: o.commit, operation: o.operation, idempotencyKey, ...(o.focus !== undefined ? { focus: o.focus } : {}) }));
+    });
+    async function read(id, cmd) {
+        const ctx = await resolveContext(context(cmd));
+        return await customerRequest(context(cmd), `/source-scans/${uuid(id)}?org_id=${encodeURIComponent(ctx.orgId)}`);
+    }
+    source.command("show <id>").action(async (id, _o, cmd) => output(await read(id, cmd)));
+    source.command("cancel <id>").action(async (id, _o, cmd) => {
+        const ctx = await resolveContext(context(cmd));
+        output(await customerRequest(context(cmd), `/source-scans/${uuid(id)}/cancel`, "POST", { orgId: ctx.orgId }));
+    });
+    source.command("wait <id>").option("--interval <seconds>", "Polling interval", positive, 5).option("--timeout <seconds>", "Maximum wait; does not cancel the job", positive, 1800)
+        .action(async (id, o, cmd) => {
+        const end = Date.now() + o.timeout * 1000;
+        for (;;) {
+            const job = await read(id, cmd);
+            if (["completed", "failed", "cancelled", "recovery_required"].includes(job.state)) {
+                output(job);
+                if (job.state !== "completed")
+                    process.exitCode = 2;
+                return;
+            }
+            if (!["queued", "running"].includes(job.state))
+                throw new UserError(`Unknown source job state: ${job.state}. Inspect source-scans show; do not resubmit.`);
+            if (Date.now() >= end)
+                throw new UserError("Wait timed out. The job was not cancelled; inspect source-scans show.");
+            await delay(Math.min(o.interval * 1000, end - Date.now()));
+        }
+    });
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@0cloud/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Standalone CLI for the 0cloud API: source scans, pentests, run status and workspace actions.",
+  "bin": {
+    "0cloud": "./dist/public/public-cli.js"
+  },
+  "main": "./dist/public/public-cli.js",
+  "files": [
+    "dist/public",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist/public', {recursive:true,force:true})\" && tsc -p tsconfig.publish.json && chmod +x dist/public/public-cli.js",
+    "dev": "tsx watch src/cli.ts",
+    "start": "node dist/public/public-cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build",
+    "build:operator": "tsc",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.1",
+    "tsx": "^4.23.13",
+    "typescript": "^5.7.2",
+    "vitest": "^5.0.1",
+    "@0cloud/cloud-contracts": "workspace:*",
+    "@0cloud/report": "workspace:*"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}