insta 0.0.32 → 0.0.34

package/README.md

@@ -184,6 +184,7 @@ build never reaches a production installer.
 | `insta approvals` | `list` · `approve` · `deny` |
 | `insta policy` | `get` · `set <action> <decision>` |
 | `insta observe` | `install` · `uninstall` · `report` · `sync` — local credential audit |
+| `insta feedback` | Report an InstaCloud-side hurdle (bug / feature-request / friction) to the team — never for the app you are building; works logged-out |
 | `insta upgrade` · `autoupdate` | Update the CLI; show or set auto-update |
 
 ## Configuration

package/dist/commands/feedback.js

@@ -0,0 +1,232 @@
+// `insta feedback` — report an InstaCloud-side hurdle to the InstaCloud team.
+//
+// Scope rule (also stated in the skill): this is for problems in OUR toolkit — the CLI, the MCP
+// server, the platform, the skills, the docs. Never for problems in the app the user is building.
+//
+// The backend is InstaCloud dogfooding itself: the "InstaCloud Agent Feedback" project runs the
+// ingest service (InsForge/insta-feedback repo) on a postgres + compute pair. It is NOT the
+// control-plane API on purpose — feedback must work logged-out, unlinked, and from insta-oss,
+// and a control-plane outage is exactly when we most want reports to still arrive.
+import { readFileSync, statSync } from 'node:fs';
+import os from 'node:os';
+import * as clack from '@clack/prompts';
+import { readGlobal, readProject } from '../config.js';
+import { envForApiUrl } from '../env.js';
+import { info, printJson } from '../util.js';
+import { clean } from '../redact.js';
+export const TYPES = ['bug', 'feature-request', 'friction', 'other'];
+export const COMPONENTS = ['cli', 'mcp', 'platform', 'skills', 'docs', 'other'];
+export const SEVERITIES = ['blocker', 'major', 'minor'];
+// Field caps mirror the ingest service's LIMITS (insta-feedback src/app.ts) — the server
+// truncates again, so a mismatch degrades gracefully instead of rejecting.
+export const LIMITS = {
+    title: 200,
+    detail: 4000,
+    area: 100,
+    command: 500,
+    error: 2000,
+    expected: 1000,
+    workaround: 1000,
+    doc: 300,
+};
+// Hardcoded in source, not injected at build time: a build-time credential silently no-ops in
+// local/tsx and fork builds, and feedback would appear to work while reports vanish. The token is
+// public by design (it ships in this file); it only deflects drive-by scanners — real abuse
+// control is server-side (per-IP rate limit + weekly dedup). Env overrides are for tests and
+// emergency rotation.
+const FEEDBACK_ENDPOINT = process.env.INSTA_FEEDBACK_URL ||
+    'https://insta-main-api-cdad9b6c.compute.instacloud.com/v1/feedback';
+const FEEDBACK_INGEST_TOKEN = process.env.INSTA_FEEDBACK_TOKEN || 'insta-feedback-public-v1';
+const FEEDBACK_TIMEOUT_MS = 10_000;
+const MAX_FILE_BYTES = 256 * 1024;
+function resolveCliVersion() {
+    // Same resolution as index.ts: the standalone binary bakes INSTA_CLI_VERSION via --define;
+    // npm/node reads the installed package.json next to dist/.
+    if (process.env.INSTA_CLI_VERSION)
+        return process.env.INSTA_CLI_VERSION;
+    try {
+        return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function requireEnum(value, allowed, flag) {
+    if (!allowed.includes(value)) {
+        throw new Error(`${flag} must be one of: ${allowed.join(', ')}`);
+    }
+    return value;
+}
+async function promptMissing(opts) {
+    clack.intro('insta feedback — report an InstaCloud-side hurdle');
+    if (!opts.type) {
+        const answer = await clack.select({
+            message: 'What kind of hurdle did you hit?',
+            options: [
+                { value: 'bug', label: 'bug — something InstaCloud should do, but does not' },
+                { value: 'feature-request', label: 'feature-request — something InstaCloud does not support yet' },
+                { value: 'friction', label: 'friction — works, but confusing or awkward' },
+                { value: 'other', label: 'other' },
+            ],
+        });
+        if (clack.isCancel(answer))
+            process.exit(0);
+        opts.type = answer;
+    }
+    if (!opts.component) {
+        const answer = await clack.select({
+            message: 'Where in the InstaCloud toolkit is the issue?',
+            options: COMPONENTS.map((c) => ({ value: c, label: c })),
+        });
+        if (clack.isCancel(answer))
+            process.exit(0);
+        opts.component = answer;
+    }
+    if (!opts.title) {
+        const answer = await clack.text({
+            message: 'One-line summary:',
+            validate: (v) => (v.trim() ? undefined : 'required'),
+        });
+        if (clack.isCancel(answer))
+            process.exit(0);
+        opts.title = answer.trim();
+    }
+    if (!opts.detail && !opts.file) {
+        const answer = await clack.text({
+            message: 'What happened, and what did you expect?',
+            validate: (v) => (v.trim() ? undefined : 'required'),
+        });
+        if (clack.isCancel(answer))
+            process.exit(0);
+        opts.detail = answer.trim();
+    }
+}
+/** Pure payload assembly (unit-tested): validation, redaction, caps, and ambient context. */
+export async function buildPayload(opts, ctx) {
+    const type = requireEnum(opts.type ?? '', TYPES, '--type');
+    const component = requireEnum(opts.component ?? '', COMPONENTS, '--component');
+    const severity = opts.severity ? requireEnum(opts.severity, SEVERITIES, '--severity') : 'minor';
+    let detail = opts.detail;
+    if (!detail && opts.file) {
+        try {
+            // detail is capped at 4000 chars — a file far beyond that is a mistake (wrong path, a log
+            // archive, a binary), so refuse before allocating it rather than truncating garbage.
+            // Regular files only: a FIFO/device node (e.g. /dev/zero) stats as size 0, sails past the
+            // byte ceiling, and then readFileSync reads unbounded.
+            const stat = statSync(opts.file);
+            if (!stat.isFile())
+                throw new Error(`--file ${opts.file} is not a regular file`);
+            const size = stat.size;
+            if (size > MAX_FILE_BYTES) {
+                throw new Error(`--file ${opts.file} is ${size} bytes — max ${MAX_FILE_BYTES} (detail is capped at ${LIMITS.detail} chars; trim the file first)`);
+            }
+            detail = readFileSync(opts.file, 'utf8');
+            if (detail.includes('\0'))
+                throw new Error(`--file ${opts.file} looks binary — feedback detail must be text`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(msg.startsWith('--file') ? msg : `--file ${opts.file}: ${msg}`);
+        }
+    }
+    const title = clean(opts.title, LIMITS.title);
+    if (!title)
+        throw new Error('--title is required (one-line summary, ≤200 chars)');
+    const cleanedDetail = clean(detail, LIMITS.detail);
+    if (!cleanedDetail)
+        throw new Error('--detail (or --file <path>) is required: what happened vs what you expected');
+    const project = await readProject();
+    const { apiUrl } = await readGlobal();
+    // envForApiUrl → null means a custom host: insta-oss or a preview deployment (see env.ts).
+    const target = envForApiUrl(apiUrl) ? 'cloud' : 'oss';
+    return {
+        type,
+        component,
+        severity,
+        title,
+        detail: cleanedDetail,
+        area: clean(opts.area, LIMITS.area),
+        command: clean(opts.command, LIMITS.command),
+        error: clean(opts.error, LIMITS.error),
+        expected: clean(opts.expected, LIMITS.expected),
+        workaround: clean(opts.workaround, LIMITS.workaround),
+        doc_ref: clean(opts.doc, LIMITS.doc),
+        source: 'cli',
+        target,
+        client_version: ctx.cliVersion,
+        node_version: process.version,
+        os: `${os.platform()} ${os.release()}`,
+        project_id: project?.projectId,
+        org_id: project?.orgId,
+        branch: project?.branch,
+    };
+}
+/** One POST, 10s timeout, zero retries — feedback is a side quest and must never hang the CLI.
+ *  Transport and server failures come back as a result, not an exception: the caller downgrades
+ *  them to a warning so a broken feedback backend can't fail the user's actual task. */
+export async function submit(payload, fetchImpl) {
+    let res;
+    try {
+        res = await fetchImpl(FEEDBACK_ENDPOINT, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${FEEDBACK_INGEST_TOKEN}`,
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(FEEDBACK_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        const timedOut = e instanceof Error && e.name === 'TimeoutError';
+        return { status: 'error', error: timedOut ? `timed out after ${FEEDBACK_TIMEOUT_MS / 1000}s` : `network error: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    let body = {};
+    try {
+        body = await res.json();
+    }
+    catch { /* non-JSON body — fall through to status handling */ }
+    if (!res.ok)
+        return { status: 'error', error: body?.error ?? `HTTP ${res.status}` };
+    return { status: body?.status === 'duplicate' ? 'duplicate' : 'received', id: body?.id ?? null };
+}
+export async function feedback(opts, deps = {}) {
+    const interactive = deps.interactive ?? (!opts.json && !!process.stdin.isTTY && !!process.stdout.isTTY);
+    const missingRequired = !opts.type || !opts.component || !opts.title || (!opts.detail && !opts.file);
+    if (missingRequired && interactive)
+        await promptMissing(opts);
+    // Bad/missing input exits 1 either way — an agent CAN fix its flags, so the error must be loud
+    // and self-teaching (it lists the exact enum values). But it must arrive on the channel the
+    // caller chose: --json gets a machine-readable object on stdout (uniform with the success and
+    // transport-failure shapes) instead of guard()'s plaintext stderr line.
+    let payload;
+    try {
+        payload = await buildPayload(opts, { cliVersion: deps.cliVersion ?? resolveCliVersion() });
+    }
+    catch (e) {
+        if (!opts.json)
+            throw e;
+        printJson({ status: 'error', submitted: false, error: e instanceof Error ? e.message : String(e) });
+        process.exitCode = 1;
+        return;
+    }
+    const result = await submit(payload, deps.fetchImpl ?? fetch);
+    if (result.status === 'error') {
+        // Deliberate exit 0: an agent CANNOT fix a down/rate-limited backend, and feedback must never
+        // fail or distract from the task the user actually asked for. Do not retry.
+        if (opts.json)
+            return printJson({ status: 'error', submitted: false, error: result.error });
+        process.stderr.write(`warning: feedback not submitted (${result.error}) — continue with your task, do not retry\n`);
+        return;
+    }
+    if (opts.json)
+        return printJson({ status: result.status, id: result.id });
+    if (result.status === 'duplicate') {
+        info(`already reported this week — bumped its count instead (id: ${result.id})`);
+    }
+    else {
+        info(`feedback submitted (id: ${result.id}) — thank you!`);
+    }
+    info('PII (emails, tokens, keys, home paths) was redacted before sending.');
+}
+//# sourceMappingURL=feedback.js.map

package/dist/commands/services.js

@@ -53,20 +53,24 @@ export function resolveServiceId(services, type, name) {
         throw new Error(`service not found: ${type} ${name}`);
     return svc.id;
 }
-// Resolve a compute service id: by name, or the sole compute service when name is omitted.
-export function resolveComputeServiceId(services, name) {
-    const compute = services.filter((s) => s.type === 'compute');
+// Resolve one service of a type: by name, or the sole one of that type when name is omitted.
+export function resolveSoleService(services, type, name) {
+    const of = services.filter((s) => s.type === type);
     if (name) {
-        const svc = compute.find((s) => s.name === name);
+        const svc = of.find((s) => s.name === name);
         if (!svc)
-            throw new Error(`compute service not found: ${name}`);
-        return svc.id;
+            throw new Error(`${type} service not found: ${name}`);
+        return svc;
     }
-    if (compute.length === 0)
-        throw new Error('no compute service in this project (add one with `insta services add compute <name>`)');
-    if (compute.length > 1)
-        throw new Error(`multiple compute services — specify one: ${compute.map((s) => s.name).join(', ')}`);
-    return compute[0].id;
+    if (of.length === 0)
+        throw new Error(`no ${type} service in this project (add one with \`insta services add ${type} <name>\`)`);
+    if (of.length > 1)
+        throw new Error(`multiple ${type} services — specify one: ${of.map((s) => s.name).join(', ')}`);
+    return of[0];
+}
+// Resolve a compute service id: by name, or the sole compute service when name is omitted.
+export function resolveComputeServiceId(services, name) {
+    return resolveSoleService(services, 'compute', name).id;
 }
 // Map service-add options to the platform POST body. Pure, so it's unit-tested without a network
 // mock (mirrors deployRequestBody in deploy.ts). Validation (which options are valid for which

package/dist/commands/storage.js

@@ -0,0 +1,173 @@
+// `insta storage` — browse, download, and delete the objects in a storage service's bucket.
+import { chmod, rename, rm, stat } from 'node:fs/promises';
+import { createWriteStream, rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { ApiClient, requireProject } from '../api.js';
+import { info, printJson, handleApproval } from '../util.js';
+import { q, resolveSoleService } from './services.js';
+import { fmtBytes } from './db.js'; // the repo's tested bytes formatter — don't grow a third copy
+function qs(params) {
+    const u = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined && v !== '')
+            u.set(k, String(v));
+    const s = u.toString();
+    return s ? `?${s}` : '';
+}
+// Page size the listing route accepts. Junk must fail here, not travel as `limit=NaN`.
+export function parseObjectLimit(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1 || n > 1000)
+        throw new Error(`--limit must be an integer 1..1000, got: ${raw}`);
+    return n;
+}
+// pure: platform path for the objects collection — GET lists it, DELETE removes one `key`.
+export function objectsPath(projectId, serviceId, params) {
+    const { limit, ...rest } = params;
+    return `/projects/${projectId}/services/${serviceId}/objects${qs({ ...rest, limit: limit === undefined ? undefined : String(limit) })}`;
+}
+// pure: the presign route — a static subpath, so keys containing `/` stay in the query.
+export function objectDownloadPath(projectId, serviceId, params) {
+    return `/projects/${projectId}/services/${serviceId}/objects/download${qs(params)}`;
+}
+// pure: one `storage list` row, size-first so the columns line up over variable-length keys.
+export function objectListLine(o) {
+    const size = typeof o.size === 'number' ? fmtBytes(o.size) : '—';
+    return `${size.padStart(10)}  ${(o.lastModified ?? '—').padEnd(24)}  ${o.key}`;
+}
+// Resolve the branch's storage service (named, or the sole one) — its bucket is what we browse.
+async function storageTarget(api, projectId, branch, name) {
+    const { services } = await api.request('GET', `/projects/${projectId}/services${q(branch)}`);
+    return resolveSoleService(services, 'storage', name);
+}
+// S3 filters by prefix only — there is no substring search, so `--prefix` is the query surface.
+export async function storageList(opts) {
+    const limit = opts.limit === undefined ? undefined : parseObjectLimit(opts.limit);
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const svc = await storageTarget(api, p.projectId, branch, opts.service);
+    const res = await api.rawRequest('GET', objectsPath(p.projectId, svc.id, { branch, prefix: opts.prefix, cursor: opts.cursor, limit }));
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const objects = res.body?.objects ?? [];
+    if (!objects.length) {
+        return info(opts.prefix ? `(no objects under prefix ${opts.prefix} in storage/${svc.name})` : `(storage/${svc.name} is empty)`);
+    }
+    for (const o of objects)
+        info(objectListLine(o));
+    const next = res.body?.nextCursor;
+    if (next)
+        info(`  (more — next page: ${nextPageCommand({ ...opts, limit }, next)})`);
+}
+// Safe unquoted in every shell we care about — no spaces, quotes, or expansion characters.
+const SHELL_SAFE = /^[\w./:@=+-]+$/;
+// The continuation must repeat the filters, or following it lists a different set. Quoting rules
+// differ between sh and PowerShell, so rather than guess the shell, a value that would need quotes
+// gets a sentence instead of syntax that is broken somewhere.
+export function nextPageCommand(opts, cursor) {
+    const values = [opts.service, opts.branch, opts.prefix, cursor].filter((v) => !!v);
+    if (!values.every((v) => SHELL_SAFE.test(v))) {
+        return `re-run this command with --cursor set to ${cursor}`;
+    }
+    const flags = [
+        opts.service ? `--service ${opts.service}` : '',
+        opts.branch ? `--branch ${opts.branch}` : '',
+        opts.prefix ? `--prefix ${opts.prefix}` : '',
+        opts.limit === undefined ? '' : `--limit ${opts.limit}`,
+        `--cursor ${cursor}`,
+    ].filter(Boolean);
+    return `insta storage list ${flags.join(' ')}`;
+}
+// pure: where the bytes land. Only the last segment is used, so no key can escape cwd.
+export function outputPath(key, output) {
+    if (output)
+        return output;
+    // Split on `\` too: a key may contain one, and on Windows that is also a separator.
+    const base = key.split(/[\\/]/).pop() ?? '';
+    if (!base)
+        throw new Error(`cannot infer a filename from key "${key}" — pass -o <file>`);
+    return base;
+}
+// Stream from the provider (never through the platform, which only signs) straight to disk, so a
+// multi-gigabyte object never has to fit in memory. Returns the byte count written.
+export async function streamPresignedTo(url, out, fetchImpl = fetch) {
+    const res = await fetchImpl(url);
+    if (!res.ok || !res.body)
+        throw new Error(`download failed: HTTP ${res.status} (a presigned URL lives ~60s — re-run to mint a fresh one)`);
+    let written = 0;
+    const counting = new TransformStream({
+        transform(chunk, controller) { written += chunk.byteLength; controller.enqueue(chunk); },
+    });
+    // Write beside the target, then rename: opening `out` directly would truncate an existing file
+    // that a failed download then deletes. Same directory keeps the rename atomic.
+    const part = `${out}.insta-part-${randomBytes(4).toString('hex')}`;
+    // A signal kills the process without unwinding, so the part file needs a synchronous sweep.
+    // Exit 128+signo, so a supervisor still reads interrupted (130) apart from terminated (143).
+    const sweep = (signo) => () => { rmSync(part, { force: true }); process.exit(128 + signo); };
+    const onInt = sweep(2);
+    const onTerm = sweep(15);
+    process.once('SIGINT', onInt);
+    process.once('SIGTERM', onTerm);
+    try {
+        await pipeline(Readable.fromWeb(res.body.pipeThrough(counting)), createWriteStream(part));
+        // Replacing a 0600 file must not widen it to the umask default the part was created with.
+        const mode = await stat(out).then((s) => s.mode, () => undefined);
+        if (mode !== undefined)
+            await chmod(part, mode);
+        await rename(part, out);
+    }
+    catch (e) {
+        await rm(part, { force: true });
+        throw e;
+    }
+    finally {
+        process.off('SIGINT', onInt);
+        process.off('SIGTERM', onTerm);
+    }
+    return written;
+}
+// Core, dependency-injected for tests (mirrors runWithSecrets): stream → disk, return byte count.
+export async function saveObject(url, out, deps = {}) {
+    return (deps.streamTo ?? streamPresignedTo)(url, out);
+}
+export async function storageGet(key, opts, deps = {}) {
+    if (!key)
+        throw new Error('key is required');
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const svc = await storageTarget(api, p.projectId, branch, opts.service);
+    const res = await api.rawRequest('GET', objectDownloadPath(p.projectId, svc.id, { branch, key }));
+    if (handleApproval(res))
+        return;
+    // --json hands over the presigned URL instead of downloading, as `insta secrets --json` does.
+    // Before outputPath, so a key with no filename still works when nothing is written to disk.
+    if (opts.json)
+        return printJson(res.body);
+    const out = outputPath(key, opts.output);
+    if (!res.body?.url)
+        throw new Error('the platform returned no download URL');
+    const bytes = await saveObject(res.body.url, out, deps);
+    info(`wrote ${fmtBytes(bytes)} to ${out} (${key} from storage/${svc.name}, branch ${branch})`);
+}
+// No prompt, matching every other destructive command here — the governance gate is the guard.
+export async function storageDelete(key, opts) {
+    if (!key)
+        throw new Error('key is required');
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const svc = await storageTarget(api, p.projectId, branch, opts.service);
+    const res = await api.rawRequest('DELETE', objectsPath(p.projectId, svc.id, { branch, key }));
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    info(`deleted ${key} from storage/${svc.name} (branch ${branch})`);
+}
+//# sourceMappingURL=storage.js.map

package/dist/index.js

@@ -19,12 +19,14 @@ import * as secretsCmd from './commands/secrets.js';
 import { deploy } from './commands/deploy.js';
 import * as computeCmd from './commands/compute.js';
 import * as dbCmd from './commands/db.js';
+import * as storageCmd from './commands/storage.js';
 import { manifest } from './commands/manifest.js';
 import * as govern from './commands/govern.js';
 import * as observe from './commands/observe.js';
 import * as obs from './commands/metrics.js';
 import { billing, billingUpgrade, billingPortal } from './commands/billing.js';
 import * as selfUpdate from './commands/upgrade.js';
+import * as feedbackCmd from './commands/feedback.js';
 function onError(e) {
     if (e instanceof ApiError)
         die(`${e.message} (HTTP ${e.status})`);
@@ -199,6 +201,25 @@ db.command('volume').description("Show or grow a postgres service's provisioned
     .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((o) => dbCmd.dbVolume(o)));
+// ---- storage (bucket objects) ----
+const storage = program.command('storage').description("Browse, download, and delete a storage service's bucket objects");
+storage.command('list').description("List the bucket's objects. S3 filters by prefix only — there is no substring search")
+    .option('--prefix <p>', 'only keys starting with this prefix (applied server-side)')
+    .option('--cursor <c>', 'continue from the nextCursor a previous page printed')
+    .option('--limit <n>', 'page size, 1..1000 (default 100)')
+    .option('--service <name>', 'storage service (default: the sole one on the branch)')
+    .option('--branch <b>', 'branch (default: current)').option('--json')
+    .action(guard((o) => storageCmd.storageList(o)));
+storage.command('get <key>').description('Download one object to disk through a short-lived presigned URL (bytes come straight from the provider)')
+    .option('-o, --output <file>', "output file (default: the key's last segment)")
+    .option('--service <name>', 'storage service (default: the sole one on the branch)')
+    .option('--branch <b>', 'branch (default: current)')
+    .option('--json', 'print the presigned URL + expiry instead of downloading')
+    .action(guard((key, o) => storageCmd.storageGet(key, o)));
+storage.command('delete <key>').description('DELETES one object from the bucket immediately — no undo, and an already-gone key still reports success (gated: storage.delete)')
+    .option('--service <name>', 'storage service (default: the sole one on the branch)')
+    .option('--branch <b>', 'branch (default: current)').option('--json')
+    .action(guard((key, o) => storageCmd.storageDelete(key, o)));
 // ---- manifest ----
 program.command('manifest').description('Print an agent-legible view of the project environments').option('--json').action(guard((o) => manifest(o)));
 // ---- regions ----
@@ -238,7 +259,24 @@ ob.command('sync').description('Upload findings into the project timeline').acti
 // ---- policy ----
 const pol = program.command('policy').description('Governance policy');
 pol.command('get').option('--json').action(guard((o) => govern.policyGet(o)));
-pol.command('set <action> <decision>').description('action: secrets.read|secrets.write|deploy|project.delete|branch.delete|service.add|service.remove|service.scale|service.upgrade|service.setAccess; decision: allow|deny|approve').action(guard((a, d) => govern.policySet(a, d)));
+pol.command('set <action> <decision>').description('action: secrets.read|secrets.write|deploy|project.delete|branch.delete|service.add|service.remove|service.scale|service.upgrade|service.setAccess|storage.read|storage.write|storage.delete; decision: allow|deny|approve').action(guard((a, d) => govern.policySet(a, d)));
+// ---- feedback (agent + human hurdle reports → the InstaCloud team) ----
+program.command('feedback')
+    .description('Report an InstaCloud-side hurdle (bug / missing feature / friction) to the InstaCloud team — about the insta toolkit itself, NEVER about the app you are building. Works logged-out and unlinked.')
+    .option('--type <type>', `what kind of hurdle: ${feedbackCmd.TYPES.join(' | ')}`)
+    .option('--component <component>', `which part of the toolkit: ${feedbackCmd.COMPONENTS.join(' | ')}`)
+    .option('--title <title>', 'one-line summary (≤200 chars)')
+    .option('--detail <text>', 'what happened vs what you expected (≤4000 chars)')
+    .option('--file <path>', 'read the detail from a file instead of --detail')
+    .option('--area <area>', 'product area, free text: deploy, branch, secrets, db, storage, compute, governance, billing, …')
+    .option('--command <cmd>', 'the insta command that hit the issue')
+    .option('--error <text>', 'error output (redacted + truncated locally before sending)')
+    .option('--expected <text>', 'what the docs/skill said should happen')
+    .option('--workaround <text>', 'what you did instead, if anything worked')
+    .option('--doc <ref>', 'doc or skill file that led you here (for stale-instruction reports)')
+    .option('--severity <severity>', `${feedbackCmd.SEVERITIES.join(' | ')} (default: minor)`)
+    .option('--json')
+    .action(guard((o) => feedbackCmd.feedback(o)));
 // ---- self-update ----
 program.command('upgrade').description('Update the insta CLI to the latest release (binary or npm install)')
     .action(guard(() => selfUpdate.upgrade()));

package/dist/redact.js

@@ -0,0 +1,78 @@
+// Local PII redaction for outbound feedback text. Pattern-based: a safety net, not a license to
+// paste credentials. The ingest service re-scrubs server-side with the same patterns
+// (insta-feedback repo), so a drift here is caught by the second pass. IPv6 and phone numbers are
+// deliberately not matched — the false-positive rate against UUIDs and hashes destroys the
+// diagnostic value of error text.
+const PATTERNS = [
+    // URL-embedded credentials: scheme://user:pass@host (DATABASE_URLs pasted into error output)
+    [/(\w+:\/\/)[^\s/@:]+:[^\s/@]+@/g, '$1[REDACTED]@'],
+    // JWTs
+    [/eyJ[\w-]{10,}\.[\w-]{10,}\.[\w-]{5,}/g, '[REDACTED_JWT]'],
+    // Bearer tokens
+    [/\b[Bb]earer\s+[\w~+/.=-]{8,}/g, 'Bearer [REDACTED]'],
+    // insta_ platform tokens are insta_ + a ≥24-char Better Auth apiKey. The tail must stay ≥24:
+    // MCP tool names (insta_feedback, insta_storage_download_url, …) share the prefix with tails
+    // up to 20 chars, and they are exactly what feedback text quotes most.
+    [/\binsta_[\w-]{24,}/g, '[REDACTED_KEY]'],
+    // Common third-party key prefixes
+    [/\b(?:uak_|sk_live_|sk_test_|whsec_|ghp_|github_pat_|npm_|AIza|xox[a-z]-)[\w-]{6,}/g, '[REDACTED_KEY]'],
+    [/\bsk-[\w-]{16,}/g, '[REDACTED_KEY]'],
+    [/\bAKIA[0-9A-Z]{12,}/g, '[REDACTED_KEY]'],
+    // Generic assignments: password=..., api_key: "..."
+    [/\b(password|passwd|pwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token)\b(\s*[:=]\s*)["']?[^\s"'&,;]{4,}["']?/gi, '$1$2[REDACTED]'],
+    // Emails
+    [/[\w.+-]+@[\w-]+\.[\w.-]+/g, '[REDACTED_EMAIL]'],
+    // Home directories carry the username (unix + windows)
+    [/\/(?:Users|home)\/[\w.-]+/g, '~'],
+    [/[A-Z]:[\\/]Users[\\/][\w.-]+/g, '~'],
+];
+// Public IPv4 only — private/loopback ranges are kept for their debug value.
+// Known asymmetry with the IPv6/phone exemption above: a 4-part version or build string whose
+// octets all fit 0–255 (e.g. "25.2.0.100") gets over-scrubbed. Accepted deliberately — dotted
+// quads in error text are overwhelmingly real addresses, an over-scrub is recoverable noise,
+// and an under-scrub is a leak; anchoring on surrounding context would trade that for misses.
+const IPV4 = /\b(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\b/g;
+function isPrivateIp(a, b) {
+    if (a === 10 || a === 127 || a === 0)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 169 && b === 254)
+        return true;
+    return false;
+}
+export function redactSensitive(text) {
+    let out = text;
+    for (const [re, sub] of PATTERNS)
+        out = out.replace(re, sub);
+    out = out.replace(IPV4, (m, a, b, c, d) => {
+        const [na, nb, nc, nd] = [Number(a), Number(b), Number(c), Number(d)];
+        if (na > 255 || nb > 255 || nc > 255 || nd > 255)
+            return m;
+        return isPrivateIp(na, nb) ? m : '[REDACTED_IP]';
+    });
+    return out;
+}
+/** Middle truncation keeping 60% head + 40% tail — the start of an error names the failure, the
+ *  end carries the actual cause; the middle is usually a stack. */
+export function truncateMiddle(text, max) {
+    if (text.length <= max)
+        return text;
+    const marker = `…[${text.length - max} chars truncated]…`;
+    const head = Math.floor(max * 0.6);
+    const tail = max - head;
+    return text.slice(0, head) + marker + text.slice(text.length - tail);
+}
+/** Redact BEFORE truncating: truncating first could leave half a token visible at the cut and the
+ *  redaction pattern would no longer match it. */
+export function clean(value, max) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    return truncateMiddle(redactSensitive(trimmed), max);
+}
+//# sourceMappingURL=redact.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [