@instafy/cli 0.1.0-staging.138

package/README.md

@@ -0,0 +1,66 @@
+# Instafy CLI (developer preview)
+
+Local helper for running the Instafy runtime (agent + origin) on desktop or self-hosted servers. Primary commands:
+
+- `instafy runtime:start` — launch the runtime in the current machine (foreground by default, `--detach` to background).
+- `instafy runtime:status` — report health of the last started runtime.
+- `instafy runtime:stop` — stop the last started runtime.
+- `instafy runtime:token` — mint a runtime access token with agent + origin scopes.
+- `instafy project:init` — create a project via the controller and write `.instafy/project.json` in the chosen folder.
+- `instafy project:list` — list projects for the orgs available to the current controller token.
+- `instafy org:list` — list orgs available to the current controller token.
+
+## Quick start
+
+```bash
+# From repo root (assumes runtime-agent is built): pnpm --filter @instafy/cli dev -- --help
+pnpm --filter @instafy/cli dev -- runtime:start \
+  --project 00000000-0000-0000-0000-000000000000 \
+  --controller-url http://127.0.0.1:8788 \
+  --controller-access-token "$CONTROLLER_ACCESS_TOKEN"
+
+# Inspect status
+pnpm --filter @instafy/cli dev -- runtime:status
+
+# Stop
+pnpm --filter @instafy/cli dev -- runtime:stop
+
+# Create a project manifest for the current directory
+pnpm --filter @instafy/cli dev -- project:init --controller-url http://127.0.0.1:8788 --access-token "$SUPABASE_ACCESS_TOKEN"
+
+# List projects for your orgs
+pnpm --filter @instafy/cli dev -- project:list --controller-url http://127.0.0.1:8788 --access-token "$SUPABASE_ACCESS_TOKEN"
+```
+
+## Auth model
+
+- The CLI mints a **runtime access token** via `/projects/:projectId/runtime/token` when a controller access token is provided (`--controller-access-token` or `CONTROLLER_ACCESS_TOKEN`).
+- That token is exported to the runtime as `RUNTIME_ACCESS_TOKEN` and mirrored to `ORIGIN_INTERNAL_TOKEN` for the bundled origin server.
+- You can supply a pre-minted token with `--runtime-token` / `RUNTIME_ACCESS_TOKEN` (also reused for origin). Legacy `--origin-token` still maps to the same value.
+- If you only have a Supabase session (service role or user JWT), pass it via `--supabase-access-token`, `--supabase-access-token-file`, or `SUPABASE_ACCESS_TOKEN`. The CLI uses that session to mint the controller and runtime tokens automatically so you do not need to juggle controller-issued keys locally.
+
+## Important flags
+
+- `--project` / `PROJECT_ID` — project UUID to associate the runtime with (defaults to `.instafy/project.json` if present).
+- `--controller-url` / `CONTROLLER_BASE_URL` — controller base URL (defaults to `http://127.0.0.1:8788`).
+- `--controller-access-token` — user/controller token used to mint the runtime token if `--runtime-token` is not provided.
+- `--supabase-access-token` / `SUPABASE_ACCESS_TOKEN` — Supabase session token the CLI can exchange for controller and runtime tokens when you do not have a controller key handy.
+- `--runtime-token` / `RUNTIME_ACCESS_TOKEN` — pre-minted runtime/origin token to bypass minting.
+- `--origin-id` — optionally fix the origin id (otherwise auto-generated).
+- `--origin-endpoint` — skip tunnels entirely and publish a fixed, reachable origin URL (useful for servers with a stable public endpoint).
+- `--workspace` / `WORKSPACE_DIR` — workspace root for the runtime (default `./.instafy/workspace`).
+- `--provider` / `RUNTIME_PROVIDER` — runtime provider label (defaults to the org in `.instafy/project.json`, otherwise `self-hosted`).
+- `--detach` — background the runtime; pid/log state is recorded under `~/.instafy/cli-runtime-state.json`.
+- `--org-id` — target an existing org when running `project:init` (otherwise the CLI creates or reuses a personal org).
+
+## Tunnels (self-hosted)
+
+Tunnels are controller-managed: the runtime-agent requests a tunnel assignment from the controller and then launches the appropriate client locally.
+
+- **Self-hosted tunnels (recommended)**: controller is configured with `TUNNEL_BROKER_BASE_URL` / `TUNNEL_BROKER_TOKEN` and returns `provider=self_hosted`. The runtime-agent launches `rathole` (outbound-only). The CLI will try to resolve `RATHOLE_BIN` (PATH or cached download). On macOS arm64, it falls back to `cargo install rathole` when no prebuilt is available.
+
+## Notes
+
+- The CLI reuses the locally built `runtime-agent` binary from `target/{debug,release}`. Run `cargo build -p runtime-agent` first or set `INSTAFY_RUNTIME_AGENT_BIN` to an explicit path.
+- Runtime/origin tokens require the controller to be configured with the Ed25519 signing pair (`RUNTIME_SIGNING_PRIVATE_KEY` / `RUNTIME_SIGNING_PUBLIC_KEY`; legacy `ORIGIN_TOKEN_*` is also accepted).
+- Logs for detached runs are written to `~/.instafy/cli-runtime-logs/*`.

package/bin/instafy.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../dist/index.js').catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,247 @@
+import { Command } from "commander";
+import { pathToFileURL } from "node:url";
+import kleur from "kleur";
+import { runtimeStart, runtimeStatus, runtimeStop, runtimeToken, mountWorkspace, } from "./runtime.js";
+import { projectInit } from "./project.js";
+import { runTunnelCommand } from "./tunnel.js";
+const program = new Command();
+program
+    .name("instafy")
+    .description("Instafy CLI — manage local/self-hosted runtimes")
+    .version("0.1.0");
+program
+    .command("runtime:start")
+    .description("Start a local Instafy runtime (agent + origin)")
+    .option("--project <id>", "Project UUID")
+    .option("--controller-url <url>", "Controller base URL")
+    .option("--controller-token <token>", "Controller access token")
+    .option("--controller-access-token <token>", "Controller-issued user token used to mint runtime/origin credentials")
+    .option("--supabase-access-token <token>", "Supabase session token used to mint controller/runtime tokens")
+    .option("--supabase-access-token-file <path>", "File containing the Supabase session token")
+    .option("--runtime-token <token>", "Pre-minted runtime access token (bypasses agent key)")
+    .option("--codex-bin <path>", "Path to codex binary (fallback to PATH)")
+    .option("--proxy-base-url <url>", "Codex proxy base URL")
+    .option("--workspace <path>", "Workspace directory (defaults to ./.instafy/workspace)")
+    .option("--origin-id <uuid>", "Origin ID to use (auto-generated if omitted)")
+    .option("--origin-endpoint <url>", "Explicit origin endpoint (skip tunnel setup when provided)")
+    .option("--origin-token <token>", "Runtime/origin access token for controller registration")
+    .option("--runtime-id <uuid>", "Runtime ID to use (bypass controller allocation)")
+    .option("--runtime-lease-id <uuid>", "Runtime lease ID to use (bypass controller allocation)")
+    .option("--display-name <name>", "Human-friendly runtime name")
+    .option("--provider <provider>", "Runtime provider label (default: self-hosted)")
+    .option("--bind-host <host>", "Origin bind host (default 127.0.0.1)")
+    .option("--bind-port <port>", "Origin bind port (default 54332)")
+    .option("--mount-controller-fs", "Mount controller workspace via SSHFS using mount-token API")
+    .option("--detach", "Run runtime in background and exit immediately")
+    .option("--log-file <path>", "Write runtime stdout/stderr to a file (implied when detached)")
+    .action(async (opts) => {
+    try {
+        await runtimeStart(opts);
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("runtime:status")
+    .description("Show runtime health (codex/proxy/controller/origin)")
+    .option("--json", "Output status as JSON")
+    .action(async (opts) => {
+    try {
+        await runtimeStatus({ json: opts.json });
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("runtime:sshfs:check")
+    .description("Verify sshfs availability and print platform-specific install hints")
+    .option("--sshfs-bin <path>", "sshfs binary (default: sshfs or SHARED_FS_BIN)")
+    .action(async (opts) => {
+    try {
+        const { checkSshfs } = await import("./runtime.js");
+        await checkSshfs(opts.sshfsBin);
+        console.log(kleur.green(`sshfs OK (${opts.sshfsBin ?? process.env.SHARED_FS_BIN ?? "sshfs"})`));
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("runtime:stop")
+    .description("Stop the local Instafy runtime")
+    .option("--json", "Output result as JSON")
+    .action(async (opts) => {
+    try {
+        await runtimeStop({ json: opts.json });
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("runtime:token")
+    .description("Mint a runtime access token (unified agent/origin scopes)")
+    .requiredOption("--project <id>", "Project UUID")
+    .option("--controller-url <url>", "Controller base URL")
+    .option("--controller-access-token <token>", "Controller access token (required)")
+    .option("--runtime-id <uuid>", "Runtime ID to bind token to")
+    .option("--scope <scope...>", "Override scopes (default agent.* + origin.*)")
+    .option("--json", "Output token as JSON")
+    .action(async (opts) => {
+    try {
+        await runtimeToken({
+            project: opts.project,
+            controllerUrl: opts.controllerUrl,
+            controllerAccessToken: opts.controllerAccessToken,
+            runtimeId: opts.runtimeId,
+            scopes: opts.scope,
+            json: opts.json,
+        });
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("project:init")
+    .description("Create a project via the controller and write .instafy/project.json in the target path")
+    .option("--path <dir>", "Directory where the manifest should be written (default: cwd)")
+    .option("--controller-url <url>", "Controller base URL")
+    .option("--access-token <token>", "Controller or Supabase access token")
+    .option("--project-type <type>", "Project type (customer|sandbox)")
+    .option("--org-id <uuid>", "Optional organization id")
+    .option("--org-name <name>", "Optional organization name")
+    .option("--org-slug <slug>", "Optional organization slug")
+    .option("--owner-user-id <uuid>", "Explicit owner user id (defaults to caller)")
+    .option("--json", "Output JSON")
+    .action(async (opts) => {
+    try {
+        await projectInit({
+            path: opts.path,
+            controllerUrl: opts.controllerUrl,
+            accessToken: opts.accessToken,
+            projectType: opts.projectType,
+            orgId: opts.orgId,
+            orgName: opts.orgName,
+            orgSlug: opts.orgSlug,
+            ownerUserId: opts.ownerUserId,
+            json: opts.json,
+        });
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("tunnel")
+    .description("Request a tunnel from the controller and forward a local port via rathole")
+    .option("--project <id>", "Project UUID (or set PROJECT_ID)")
+    .option("--controller-url <url>", "Controller base URL (or CONTROLLER_URL)")
+    .option("--controller-token <token>", "Controller access token (service-role/internal)")
+    .option("--port <port>", "Local port to expose (default 3000)")
+    .option("--rathole-bin <path>", "Path to rathole binary (or set RATHOLE_BIN)")
+    .action(async (opts) => {
+    try {
+        const port = opts.port ? Number(opts.port) : undefined;
+        await runTunnelCommand({
+            project: opts.project,
+            controllerUrl: opts.controllerUrl,
+            controllerToken: opts.controllerToken,
+            port,
+            ratholeBin: opts.ratholeBin,
+        });
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("org:list")
+    .description("List organizations accessible to the current access token")
+    .option("--controller-url <url>", "Controller base URL")
+    .option("--access-token <token>", "Controller or Supabase access token")
+    .option("--json", "Output JSON")
+    .action(async (opts) => {
+    try {
+        await (await import("./org.js")).listOrganizations({
+            controllerUrl: opts.controllerUrl,
+            accessToken: opts.accessToken,
+            json: opts.json,
+        });
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("project:list")
+    .description("List projects in your organizations")
+    .option("--controller-url <url>", "Controller base URL")
+    .option("--access-token <token>", "Controller or Supabase access token")
+    .option("--org-id <uuid>", "Filter by organization id")
+    .option("--org-slug <slug>", "Filter by organization slug")
+    .option("--json", "Output JSON")
+    .action(async (opts) => {
+    try {
+        await (await import("./project.js")).listProjects({
+            controllerUrl: opts.controllerUrl,
+            accessToken: opts.accessToken,
+            orgId: opts.orgId,
+            orgSlug: opts.orgSlug,
+            json: opts.json,
+        });
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("workspace:mount")
+    .description("Mount the controller-managed workspace locally over SSHFS")
+    .requiredOption("--project <id>", "Project UUID")
+    .requiredOption("--path <dir>", "Local mount directory")
+    .option("--controller-url <url>", "Controller base URL", "http://127.0.0.1:8788")
+    .option("--controller-access-token <token>", "Controller access token (service-role or project member)")
+    .option("--sshfs-bin <path>", "sshfs binary (default: sshfs or SHARED_FS_BIN)")
+    .option("--options <opts>", "Extra sshfs options")
+    .action(async (opts) => {
+    try {
+        const token = opts.controllerAccessToken ??
+            process.env.CONTROLLER_ACCESS_TOKEN ??
+            process.env.CONTROLLER_TOKEN;
+        if (!token) {
+            throw new Error("controller access token is required for workspace:mount");
+        }
+        const mountDir = await mountWorkspace({
+            project: opts.project,
+            controllerUrl: opts.controllerUrl,
+            controllerAccessToken: token,
+            mountPath: opts.path,
+            sshfsBin: opts.sshfsBin,
+            extraOptions: opts.options,
+        });
+        console.log(kleur.green(`Mounted controller workspace to ${mountDir}`));
+    }
+    catch (error) {
+        console.error(kleur.red(String(error)));
+        process.exit(1);
+    }
+});
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    program.parseAsync(process.argv);
+}
+// Re-export programmatic APIs for embedders (e.g., VS Code extension).
+export { runtimeStart as startRuntime, runtimeStatus as getRuntimeStatus, runtimeStop as stopRuntime, runtimeToken as mintRuntimeToken, mintRuntimeAccessToken, findProjectManifest, mountWorkspace, } from "./runtime.js";
+export { projectInit, listProjects } from "./project.js";
+export { listOrganizations } from "./org.js";

package/dist/org.js

@@ -0,0 +1,46 @@
+import kleur from "kleur";
+function normalizeUrl(raw) {
+    const value = (raw ?? "").trim();
+    if (!value)
+        return "http://127.0.0.1:8788";
+    return value.replace(/\/$/, "");
+}
+function normalizeToken(raw) {
+    if (!raw)
+        return null;
+    const trimmed = raw.trim();
+    return trimmed.length ? trimmed : null;
+}
+export async function listOrganizations(params) {
+    const controllerUrl = normalizeUrl(params.controllerUrl ?? process.env["CONTROLLER_BASE_URL"]);
+    const token = normalizeToken(params.accessToken) ??
+        normalizeToken(process.env["CONTROLLER_ACCESS_TOKEN"]) ??
+        normalizeToken(process.env["SUPABASE_ACCESS_TOKEN"]);
+    if (!token) {
+        throw new Error("Controller access token is required (--access-token, CONTROLLER_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
+    }
+    const response = await fetch(`${controllerUrl}/orgs`, {
+        headers: { authorization: `Bearer ${token}` },
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`Organization list failed (${response.status} ${response.statusText}): ${text}`);
+    }
+    const body = (await response.json());
+    const orgs = Array.isArray(body.orgs) ? body.orgs : [];
+    if (params.json) {
+        console.log(JSON.stringify(orgs, null, 2));
+    }
+    else {
+        if (orgs.length === 0) {
+            console.log(kleur.yellow("No organizations found for this account."));
+        }
+        else {
+            for (const org of orgs) {
+                const role = org.role ? ` [${org.role}]` : "";
+                console.log(`${kleur.green(org.name)} (${org.id}${role})`);
+            }
+        }
+    }
+    return orgs;
+}

package/dist/project.js

@@ -0,0 +1,184 @@
+import fs from "node:fs";
+import path from "node:path";
+import kleur from "kleur";
+function normalizeUrl(raw) {
+    const value = (raw ?? "").trim();
+    if (!value)
+        return "http://127.0.0.1:8788";
+    return value.replace(/\/$/, "");
+}
+function normalizeToken(raw) {
+    if (!raw)
+        return null;
+    const trimmed = raw.trim();
+    return trimmed.length ? trimmed : null;
+}
+async function fetchOrganizations(controllerUrl, token) {
+    const response = await fetch(`${controllerUrl}/orgs`, {
+        headers: {
+            authorization: `Bearer ${token}`,
+        },
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`Organization list failed (${response.status} ${response.statusText}): ${text}`);
+    }
+    const body = (await response.json());
+    return Array.isArray(body.orgs) ? body.orgs : [];
+}
+async function fetchOrgProjects(controllerUrl, token, orgId) {
+    const response = await fetch(`${controllerUrl}/orgs/${encodeURIComponent(orgId)}/projects`, {
+        headers: {
+            authorization: `Bearer ${token}`,
+        },
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`Project list failed (${response.status} ${response.statusText}): ${text}`);
+    }
+    const body = (await response.json());
+    return Array.isArray(body.projects) ? body.projects : [];
+}
+async function resolveOrg(controllerUrl, token, options) {
+    if (options.orgId) {
+        return { orgId: options.orgId, orgName: options.orgName ?? null };
+    }
+    const payload = {};
+    if (options.orgName) {
+        payload.orgName = options.orgName;
+    }
+    if (options.orgSlug) {
+        payload.orgSlug = options.orgSlug;
+    }
+    if (options.ownerUserId) {
+        payload.ownerUserId = options.ownerUserId;
+    }
+    const response = await fetch(`${controllerUrl}/orgs`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${token}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`Organization creation failed (${response.status} ${response.statusText}): ${text}`);
+    }
+    const json = (await response.json());
+    const orgId = json.org_id;
+    if (!orgId) {
+        throw new Error("Organization creation response missing org_id");
+    }
+    return { orgId, orgName: json.org_name ?? null };
+}
+export async function listProjects(options) {
+    const controllerUrl = normalizeUrl(options.controllerUrl ?? process.env["CONTROLLER_BASE_URL"]);
+    const token = normalizeToken(options.accessToken) ??
+        normalizeToken(process.env["CONTROLLER_ACCESS_TOKEN"]) ??
+        normalizeToken(process.env["SUPABASE_ACCESS_TOKEN"]);
+    if (!token) {
+        throw new Error("Controller or Supabase access token is required (--access-token, CONTROLLER_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
+    }
+    const orgs = await fetchOrganizations(controllerUrl, token);
+    let targetOrgs = orgs;
+    if (options.orgId) {
+        targetOrgs = orgs.filter((org) => org.id === options.orgId);
+        if (targetOrgs.length === 0) {
+            throw new Error(`No organization found for id ${options.orgId}`);
+        }
+    }
+    else if (options.orgSlug) {
+        targetOrgs = orgs.filter((org) => org.slug === options.orgSlug);
+        if (targetOrgs.length === 0) {
+            throw new Error(`No organization found for slug ${options.orgSlug}`);
+        }
+    }
+    const summaries = [];
+    for (const org of targetOrgs) {
+        const projects = await fetchOrgProjects(controllerUrl, token, org.id);
+        summaries.push({ org, projects });
+    }
+    if (options.json) {
+        console.log(JSON.stringify(summaries, null, 2));
+    }
+    else if (summaries.length === 0) {
+        console.log(kleur.yellow("No organizations found for this account."));
+    }
+    else {
+        for (const summary of summaries) {
+            console.log(`${kleur.green(summary.org.name)} (${summary.org.id})`);
+            if (summary.projects.length === 0) {
+                console.log(kleur.yellow("  No projects found."));
+                continue;
+            }
+            for (const project of summary.projects) {
+                const type = project.project_type ? ` · ${project.project_type}` : "";
+                const status = project.status ? ` · ${project.status}` : "";
+                console.log(`  ${project.project_id}${type}${status}`);
+            }
+        }
+    }
+    return summaries.flatMap((summary) => summary.projects);
+}
+export async function projectInit(options) {
+    const rootDir = path.resolve(options.path ?? process.cwd());
+    const controllerUrl = normalizeUrl(options.controllerUrl ?? process.env["CONTROLLER_BASE_URL"]);
+    const token = normalizeToken(options.accessToken) ??
+        normalizeToken(process.env["CONTROLLER_ACCESS_TOKEN"]) ??
+        normalizeToken(process.env["SUPABASE_ACCESS_TOKEN"]);
+    if (!token) {
+        throw new Error("Controller or Supabase access token is required (--access-token, CONTROLLER_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
+    }
+    const org = await resolveOrg(controllerUrl, token, options);
+    const body = {
+        projectType: options.projectType,
+        ownerUserId: options.ownerUserId,
+    };
+    const response = await fetch(`${controllerUrl}/orgs/${encodeURIComponent(org.orgId)}/projects`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${token}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`Project creation failed (${response.status} ${response.statusText}): ${text}`);
+    }
+    const json = (await response.json());
+    const manifestDir = path.join(rootDir, ".instafy");
+    const manifestPath = path.join(manifestDir, "project.json");
+    try {
+        fs.mkdirSync(manifestDir, { recursive: true });
+        fs.writeFileSync(manifestPath, JSON.stringify({
+            projectId: json.project_id,
+            orgId: json.org_id ?? org.orgId ?? null,
+            orgName: json.org_name ?? org.orgName ?? null,
+            controllerUrl,
+            createdAt: new Date().toISOString(),
+        }, null, 2), "utf8");
+    }
+    catch (error) {
+        throw new Error(`Project created but failed to write manifest at ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            projectId: json.project_id,
+            orgId: json.org_id ?? org.orgId ?? null,
+            orgName: json.org_name ?? org.orgName ?? null,
+            manifest: manifestPath,
+        }));
+    }
+    else {
+        console.log(kleur.green(`Project created: ${json.project_id}`));
+        const resolvedOrgName = json.org_name ?? org.orgName;
+        const resolvedOrgId = json.org_id ?? org.orgId;
+        if (resolvedOrgName) {
+            console.log(kleur.cyan(`Org: ${resolvedOrgName}${resolvedOrgId ? ` (${resolvedOrgId})` : ""}`));
+        }
+        console.log(kleur.cyan(`Manifest written to ${manifestPath}`));
+    }
+    return json;
+}