@somewhere-tech/cli 0.30.2 → 0.31.1

package/README.md

@@ -46,7 +46,7 @@ After `somewhere init`, Claude Code and Codex auto-connect via the `.mcp.json` i
 | `somewhere project view [name]` | Show project details |
 | `somewhere project delete <name>` | Delete with email confirmation |
 | `somewhere dev` | Serve your app on localhost, compiled by the platform's own compiler; save a file and the page updates in milliseconds |
-| `somewhere dev --cloud` | Deploy every save to a shareable private preview URL instead of serving locally |
+| `somewhere preview` | Run your app on the platform instead of your machine — every save goes to a private URL, and production is untouched until you promote |
 | `somewhere dev <cmd...>` | Run your own command locally with the project's env vars injected |
 | `somewhere deploy` | Deploy current directory to linked project |
 | `somewhere deploy --dry-run` | Preview the deploy diff without shipping |
@@ -234,24 +234,40 @@ Environment variables come from a `.env` in the project directory. Run
 on the platform), then fill in the ones you want locally. `somewhere dev`
 names any key the project expects that has no local value.
 
-### `--cloud`
+## `somewhere preview`
 
-`somewhere dev --cloud` deploys every save to a shareable private preview URL
-instead of serving locally, and prints the preview capability URL and the
-`somewhere promote` command after each update. Use it when you want a URL to
-send someone, or when the agent doing the work reaches the platform only over
-MCP and has no local machine to serve from. It needs the development
-environment, which is on the Pro and Scale plans and is enabled per account;
-without it the command returns `CLOUD_DEV_NOT_ENABLED`. Serving locally has no
-such requirement, on any plan.
+There are two loops, and they are named after where the app runs.
+`somewhere dev` runs it on your machine. `somewhere preview` runs it on the
+platform.
 
-A private preview is a candidate built against your live version, so a project
-that has never been published has nothing for the first one to build on. On
-such a project `--cloud` publishes once — it says so before it does — and every
+`somewhere preview` sends every save to a private URL, reachable only by you
+until you share the link. The build is the one production would get. The
+database is a separate copy of your schema with none of your production rows,
+so nothing you try in a preview can touch real data. After each update the
+command prints that URL and the `somewhere promote` command that makes those
+exact bytes live. Reach for it when you want a URL to send someone, or when the
+agent doing the work reaches the platform over MCP and has no local machine to
+serve from.
+
+Nothing your users see changes while you preview. Production keeps serving what
+you last promoted.
+
+The URL is single-use and short-lived by design: opening it exchanges it for a
+private session in that browser, and saving a file replaces it with a new one.
+Use the newest URL the command printed. Anyone without a live URL — signed out,
+or signed in as someone else — gets a 404.
+
+A preview is built against your live version, so a project that has never been
+published has nothing for the first one to build on. On such a project
+`somewhere preview` publishes once — it says so before it does — and every
 preview after that stays private to you and never changes what is live.
 
-`somewhere dev --local` is accepted for compatibility and does what bare
-`somewhere dev` does.
+`somewhere preview` is on the Pro and Scale plans. `somewhere dev` runs the same
+app on your machine on every plan, and deploying is unaffected on every plan.
+
+`somewhere dev --cloud` still starts the same loop and points you at the new
+name. `somewhere dev --local` is accepted and does what bare `somewhere dev`
+does.
 
 ### Running your own command
 

package/dist/commands/dev.js

@@ -5,6 +5,7 @@ import { join, relative } from 'node:path';
 import { reportTypecheck } from './typecheck.js';
 import { runTypecheck } from '../lib/typecheck.js';
 import chokidar from 'chokidar';
+import prompts from 'prompts';
 import open from '../lib/open.js';
 import ora from '../lib/spinner.js';
 import { ApiClient, CliApiError, LONG_CALL_TIMEOUT_MS } from '../lib/client.js';
@@ -26,6 +27,29 @@ import { isRecord, unwrapPlatformData } from '../lib/platform-command.js';
 const WATCH_EXTS = /\.(ts|tsx|js|jsx|mjs|html|css|json|svg|md|txt|png|jpe?g|gif|webp|ico|woff2?|ttf|otf)$/i;
 const DEBOUNCE_MS = 500;
 const RETRYABLE_DRAFT_CODES = new Set(['TIMEOUT', 'SERVER_SLOW', 'NETWORK_ERROR']);
+/**
+ * The preview this loop was watching has finished — it was promoted, or closed.
+ *
+ * A promote ends the preview session, but the watcher used to keep running and
+ * keep failing, once per save, with the platform's API-client wording
+ * (tsk_74375b3c). The loop knows perfectly well what happened; it should stop
+ * and say so, not relay a refusal written for a machine.
+ */
+class PreviewFinishedError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = 'PreviewFinishedError';
+    }
+}
+/** Did the platform just tell us this preview is over? */
+function previewFinishedReason(err) {
+    if (!(err instanceof CliApiError) || err.code !== 'DRAFT_SESSION_TERMINAL')
+        return null;
+    const status = err.data?.terminal_status;
+    return status === 'promoted' ? 'promoted' : 'closed';
+}
 export async function mintPreviewHandoff(client, projectId, draftId, candidateReleaseId) {
     const cap = await client.call('POST', `/projects/${encodeURIComponent(projectId)}/preview/mint`, { draft_id: draftId, candidate_release_id: candidateReleaseId });
     if (!cap || typeof cap.preview_url !== 'string' || !cap.preview_url.includes('/__sw_cap?t=')) {
@@ -65,6 +89,22 @@ export async function callDraftCandidate(client, path, body) {
         });
     }
 }
+export function registerPreview(program) {
+    program
+        .command('preview')
+        .description('Run your app on the platform instead of your machine. Every save goes to a private URL, '
+        + 'reachable only by you until you share the link. The build is the one production would get; '
+        + 'the database is a separate copy of your schema, so nothing you try here can touch production '
+        + 'rows. Nothing your users see changes — production keeps serving what you last promoted, until '
+        + 'you run `somewhere promote`. Reach for this when you want the real hosted app in front of you, '
+        + 'or when your agent reaches the platform over MCP and cannot serve on localhost. '
+        + 'Available on the Pro and Scale plans; `somewhere dev` runs the app on your machine on every plan.')
+        .option('--project <id>', 'Override project ID')
+        .option('--publish-first', 'For a project that has never been published: publish this directory to production first, so the preview has a live version to build on. Without it you are asked, and a script that cannot be asked is refused.')
+        .action(async (opts) => {
+        await runHotDeploy(opts);
+    });
+}
 export function registerDev(program) {
     program
         .command('dev [cmd...]')
@@ -75,10 +115,11 @@ export function registerDev(program) {
         'production app, and this is a faster window onto it. Same app, same build. ' +
         'Reaching the project DATABASE from the local loop is a plan feature and the command says so ' +
         'once at startup when your plan does not include it; deploying is unaffected on every plan. ' +
-        '--cloud deploys every save to a shareable private preview URL instead of serving locally. ' +
+        'To see the same app running on the platform instead of your machine, use `somewhere preview`. ' +
         'Pass a command (e.g. `somewhere dev npm run dev`) to run it locally with platform env vars.')
         .option('--project <id>', 'Override project ID')
-        .option('--cloud', 'Deploy every save to a shareable private preview URL instead of serving locally — the loop for an agent that reaches the platform only over MCP')
+        .option('--cloud', 'Alias for `somewhere preview`')
+        .option('--publish-first', 'Only with `--cloud`: see `somewhere preview --help`')
         .option('--port <port>', 'Port to serve on (default 8787)')
         .option('--open', 'Open the app in your browser once it is serving')
         .option('--check', 'Typecheck (tsc --noEmit) before starting and EXIT on type errors instead of warning. Needs `npm install` in this directory — tsc reads package types out of node_modules, which the CLI\'s own dependency cache does not stand in for.')
@@ -90,6 +131,9 @@ export function registerDev(program) {
             return runLegacyExec(cmdParts);
         }
         if (opts.cloud) {
+            // Pre-launch alias. One line, then the identical loop — no ceremony,
+            // no grandfathering. `preview` is the name.
+            info('This is `somewhere preview`. Use that name — `--cloud` still works for now.');
             return runHotDeploy(opts);
         }
         return runLocalDev(opts);
@@ -369,16 +413,22 @@ export function localDevDbNotice(allowed, plans = []) {
         'Deploying is unaffected on every plan: `somewhere deploy` publishes to production and the deployed app reads and writes the database normally.',
     ];
 }
-export const CLOUD_DEV_UNAVAILABLE_MESSAGE = 'Private previews (`somewhere dev --cloud`) are available on the Pro and Scale plans. '
-    + 'This account is on a plan that does not include them.';
+export const CLOUD_DEV_UNAVAILABLE_MESSAGE = '`somewhere preview` is available on the Pro and Scale plans. '
+    + 'This account is on a plan that does not include it.';
 /**
  * Does this account have private previews?
  *
  * Returns `true`/`false` when the platform states it, and `null` when it does
  * not — a read that fails, or a platform that stopped reporting the field.
- * `null` must NEVER refuse: an unknown answer is not a denial, and blocking
- * someone whose account works today would be a worse bug than the one this
- * check exists to fix. Only an explicit `false` stops the command.
+ * `null` must NEVER refuse: an unknown answer is not a denial, and telling
+ * someone whose account works today to upgrade would be a worse bug than the
+ * one this check exists to fix. Only an explicit `false` stops the command.
+ *
+ * That is safe HERE, and only here, because of where the answer is used: an
+ * unknown entitlement is read on the path that already requires explicit
+ * consent to publish (see resolveBaseRelease), so it can no longer wave through
+ * a production release nobody asked for. It is the RELEASE read, not this one,
+ * that must refuse when it cannot answer.
  *
  * On a never-published project the platform answers this with the plain plan
  * entitlement (there is no release to bind a preview to yet), which is exactly
@@ -403,45 +453,142 @@ export class CloudDevUnavailableError extends Error {
         this.name = 'CloudDevUnavailableError';
     }
 }
-/** The project's current live release, or null when it has never published. */
-export async function readActiveReleaseId(projectId) {
+/**
+ * Read the project's live version, distinguishing "nothing is live" from
+ * "could not tell". Every failure mode — a refusal, a server error, a dropped
+ * connection, a 200 whose shape this CLI does not recognise — is `unknown`.
+ *
+ * `call` is injected so a fixture can drive each of those answers.
+ */
+export async function readBaseReleaseState(projectId, call = callPlatformTool) {
+    let status;
     try {
-        const status = unwrapPlatformData(await callPlatformTool('deploy_status', { project_id: projectId }, { allTools: true }));
-        if (isRecord(status) && typeof status.active_release_id === 'string') {
-            return status.active_release_id;
-        }
+        status = unwrapPlatformData(await call('deploy_status', { project_id: projectId }, { allTools: true }));
     }
-    catch {
-        // Non-fatal: the caller treats "unknown" as "no base" and the deploy validates.
+    catch (err) {
+        return { known: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+    if (!isRecord(status)) {
+        return { known: false, reason: 'the platform did not describe this project.' };
+    }
+    if (typeof status.active_release_id === 'string') {
+        return { known: true, activeReleaseId: status.active_release_id };
+    }
+    // The ONLY answer that may lead to a publish: the platform states this
+    // project is not published. Note the deliberate asymmetry — a project that IS
+    // published but does not name a version behind it falls through to unknown
+    // below rather than being treated as never-published, because the cost of
+    // being wrong in that direction is publishing over a live app.
+    if (status.published === false)
+        return { known: true, activeReleaseId: null };
+    return {
+        known: false,
+        reason: 'the platform did not say which version of this project is live.',
+    };
+}
+/** The live version could not be read, so nothing may be published over it. */
+export class BaseReleaseUnknownError extends Error {
+    reason;
+    code = 'BASE_RELEASE_UNKNOWN';
+    constructor(reason) {
+        super('Could not tell whether this project already has a live version, so nothing was published. '
+            + `The platform said: ${reason}`);
+        this.reason = reason;
+        this.name = 'BaseReleaseUnknownError';
     }
-    return null;
 }
 /**
- * Guarantee there is a live version for a private preview to build on,
- * publishing once if there is none.
+ * Publishing this directory to production was never agreed to.
  *
- * THE ORDER IS THE CONTRACT (tsk_cf48f4ab). A private preview builds a
- * candidate against the project's live version, so a never-published project
- * has nothing to build on and the platform refuses. Publishing once here — out
- * loud, never silently — is what makes `somewhere dev --cloud` work on a brand
- * new project. But private previews are also a plan feature, and the platform
- * enforces that on the preview request, which is the step AFTER this publish.
- * So the entitlement is read FIRST: an account without private previews is
- * refused having created nothing, instead of being handed a live production
- * version it never asked for and then told the command is unavailable.
+ * `declined` — asked, and the answer was no.
+ * `not-asked` — nothing here could ask (a script, an agent, a piped shell), so
+ * the answer is no by default. Consent that cannot be given is not consent.
+ */
+export class PublishConsentRequiredError extends Error {
+    why;
+    code = 'PUBLISH_CONSENT_REQUIRED';
+    constructor(why) {
+        super('Nothing was published.');
+        this.why = why;
+        this.name = 'PublishConsentRequiredError';
+    }
+}
+/**
+ * Find the live version a private preview will build on — and, on a project
+ * that has none, publish one ONLY after the person running the command says so.
+ *
+ * THE ORDER IS THE CONTRACT (tsk_cf48f4ab, tsk_5504e045). Every step below is
+ * placed so that the customer's live site cannot change as a side effect of
+ * asking for a preview:
+ *
+ *   1. The plan entitlement is read FIRST, before any write and before any
+ *      question. An account without private previews is refused having created
+ *      nothing, rather than handed a production release and then told the
+ *      command is unavailable.
+ *   2. The live version is read, and an unreadable answer STOPS the command.
+ *      This is the reversal: `null` used to mean both "nothing is live" and
+ *      "I could not tell", and the second one published over live projects.
+ *   3. A project that already has a live version returns it and publishes
+ *      NOTHING. This is the overwhelmingly common path.
+ *   4. Only a positively-confirmed "never published" reaches the publish, and
+ *      only after explicit consent — a confirmation, or `--publish-first`.
  *
- * `publish` is injected so a fixture can prove it was never called on the
- * refusal path — the ordering is the behaviour under test, not the call shape.
+ * Why an unknown ENTITLEMENT does not refuse here, when an unknown RELEASE
+ * does: the entitlement question is only ever asked on the path that already
+ * requires the customer's explicit consent to publish, and consent settles it.
+ * A working account is never blocked by a read that failed; it is only ever
+ * asked. Only a stated `false` refuses, so nobody is told to upgrade on the
+ * strength of a read that did not answer.
+ *
+ * `publish` and `confirmPublish` are injected so a fixture can prove `publish`
+ * was never called on each refusal path — the ordering is the behaviour under
+ * test, not the call shape.
  */
-export async function ensureBaseRelease(args) {
-    // Only an explicit `false` refuses; `null` means the platform did not say,
-    // and an unknown answer must never block an account that works today.
+export async function resolveBaseRelease(args) {
     if ((await args.cloudDevAllowed()) === false)
         throw new CloudDevUnavailableError();
+    const state = await args.readBaseReleaseState();
+    if (!state.known)
+        throw new BaseReleaseUnknownError(state.reason);
+    if (state.activeReleaseId)
+        return { baseReleaseId: state.activeReleaseId, published: false };
     args.announce?.('This project has never been published, so there is no live version for a private preview to build on.');
-    args.announce?.('Publishing it once now to create the first version. After this, every preview stays private to you.');
+    args.announce?.('Publishing it once now would put the files in this directory in front of your users. '
+        + 'After that, every preview stays private to you and production only changes when you promote.');
+    const consent = await args.confirmPublish();
+    if (consent !== 'granted')
+        throw new PublishConsentRequiredError(consent);
     await args.publish();
-    return args.readActiveReleaseId();
+    const after = await args.readBaseReleaseState();
+    if (!after.known || !after.activeReleaseId) {
+        throw new BaseReleaseUnknownError('the first version was published, but the live version could not be read back. '
+            + 'Run `somewhere preview` again.');
+    }
+    return { baseReleaseId: after.activeReleaseId, published: true };
+}
+/**
+ * Ask, once, before the one thing `somewhere preview` can do to a live site.
+ *
+ * A prompt is the primary mechanism rather than a bare flag because the publish
+ * happens on a FIRST run, when nobody knows a flag is needed — a flag-only
+ * design would either block every interactive first run or, worse, be added
+ * blindly and re-open the hole. A prompt nobody can answer is not consent
+ * either, so a non-interactive shell (a script, an agent, a piped terminal)
+ * gets `not-asked` and the refusal names `--publish-first`, which is the same
+ * consent given up front.
+ */
+export async function readPublishConsent(publishFirst) {
+    if (publishFirst)
+        return 'granted';
+    if (!process.stdin.isTTY)
+        return 'not-asked';
+    const { ok } = await prompts({
+        type: 'confirm',
+        name: 'ok',
+        message: 'Publish this directory to production now, so the preview has a live version to build on?',
+        initial: false,
+    });
+    return ok === true ? 'granted' : 'declined';
 }
 async function runHotDeploy(opts) {
     const token = getToken();
@@ -459,60 +606,73 @@ async function runHotDeploy(opts) {
         subdomain = config.subdomain;
     }
     await showProjectNotices(client, projectId);
-    // Initial full sync to the PREVIEW slot (preview: true). Writes only the
-    // owner-gated dev slot — never prod, never a version bump or history entry.
-    // /deploy/patch rejects projects with no prior deploy, so a full (preview)
-    // deploy first establishes the sandbox AND returns the {slug}-dev URL.
-    const spinner = ora('Syncing to preview...').start();
     const { files, binaryFiles, functions } = collectFiles(cwd);
     const draftId = `draft_${randomUUID()}`;
     const firstOperationId = `previewop_${randomUUID()}`;
-    // The first preview snapshot must name the production release it was read from
-    // (base_release_id) — the platform binds the draft to that exact production
-    // release. Read it from deploy_status; a project that has never published to
-    // production has no base and starts the draft from empty.
-    let baseReleaseId = await readActiveReleaseId(projectId);
-    // An exact preview builds a private CANDIDATE against the project's live
-    // version. A project that has never been published has no live version, so
-    // there is nothing for the first candidate to build on and the platform
-    // refuses with PREVIEW_REQUIRES_BASE_RELEASE. Publish once here — announced,
-    // never silently — so `somewhere dev` works on a brand-new project. Every
-    // preview after this stays private and never changes what is live.
-    if (!baseReleaseId) {
-        spinner.stop();
-        try {
-            baseReleaseId = await ensureBaseRelease({
-                cloudDevAllowed: () => readCloudDevAllowed(projectId),
-                announce: info,
-                publish: async () => {
-                    await callDraftCandidate(client, '/deploy', {
-                        project_id: projectId,
-                        scope: 'all',
-                        files,
-                        binary_files: binaryFiles,
-                        functions,
-                        replace_functions: true,
-                    });
-                },
-                readActiveReleaseId: () => readActiveReleaseId(projectId),
-            });
+    // The first preview snapshot must name the production release it was read
+    // from (base_release_id) — the platform binds the preview to that exact
+    // production release. Everything about how that id is obtained, including
+    // the refusal to invent one, lives in resolveBaseRelease.
+    let baseReleaseId;
+    try {
+        const resolved = await resolveBaseRelease({
+            cloudDevAllowed: () => readCloudDevAllowed(projectId),
+            readBaseReleaseState: () => readBaseReleaseState(projectId),
+            confirmPublish: () => readPublishConsent(opts.publishFirst === true),
+            announce: info,
+            publish: async () => {
+                await callDraftCandidate(client, '/deploy', {
+                    project_id: projectId,
+                    scope: 'all',
+                    files,
+                    binary_files: binaryFiles,
+                    functions,
+                    replace_functions: true,
+                });
+            },
+        });
+        baseReleaseId = resolved.baseReleaseId;
+        if (resolved.published)
             success('Published — this project now has a live version.');
+    }
+    catch (err) {
+        // Every branch here says the same thing in different words: your live site
+        // is exactly as you left it. Nothing below may claim anything about whether
+        // this project is published — that is precisely the read that failed.
+        if (err instanceof CloudDevUnavailableError) {
+            error(err.message);
+            info('Nothing was created or changed — whatever is live stays live.');
+            info('`somewhere deploy` publishes to production on any plan, and `somewhere dev` runs the same app on your machine.');
+            process.exit(1);
         }
-        catch (err) {
-            if (err instanceof CloudDevUnavailableError) {
-                error(err.message);
-                info('Nothing was created — this project has not been published.');
-                info('`somewhere deploy` publishes to production on any plan, and `somewhere dev` runs the same app locally.');
-                process.exit(1);
+        if (err instanceof BaseReleaseUnknownError) {
+            error(err.message);
+            info('Nothing was created or changed — whatever is live stays live.');
+            info('Try `somewhere preview` again. To publish this directory to production deliberately, run `somewhere deploy`.');
+            process.exit(1);
+        }
+        if (err instanceof PublishConsentRequiredError) {
+            if (err.why === 'declined') {
+                warn('Nothing was published — whatever is live stays live.');
             }
-            if (!(isBuildError(err) && renderBuildError(err, cwd))) {
-                error(err instanceof Error ? err.message : String(err));
+            else {
+                error('This project has never been published, so a preview has no live version to build on.');
+                info('Re-run as `somewhere preview --publish-first` to publish this directory to production first, or run `somewhere deploy` yourself.');
+                info('Nothing was created or changed — whatever is live stays live.');
             }
-            error('Could not publish the first version, so the private preview has nothing to build on.');
             process.exit(1);
         }
-        spinner.start('Syncing to preview...');
+        if (!(isBuildError(err) && renderBuildError(err, cwd))) {
+            error(err instanceof Error ? err.message : String(err));
+        }
+        error('Could not publish the first version, so the private preview has nothing to build on.');
+        process.exit(1);
     }
+    // Initial full sync to the PREVIEW slot (preview: true). Writes only the
+    // owner-gated dev slot — never prod, never a version bump or history entry.
+    // /deploy/patch rejects projects with no prior deploy, so a full (preview)
+    // deploy first establishes the sandbox AND returns the {slug}-dev URL.
+    const spinner = ora('Syncing to preview...').start();
     let candidateReleaseId = null;
     let initialHandoff;
     let initialAutoOpenUrl;
@@ -603,6 +763,24 @@ async function runHotDeploy(opts) {
             if (nextCandidate)
                 candidateReleaseId = nextCandidate;
         }
+        catch (err) {
+            if (!(err instanceof PreviewFinishedError))
+                throw err;
+            // One line, in the two words the product uses, naming the next command.
+            // Nothing about how a preview is built reaches this terminal.
+            console.log('');
+            if (err.reason === 'promoted') {
+                success('Promoted — this preview is now your live app, and the preview has finished.');
+            }
+            else {
+                info('This preview has finished.');
+            }
+            info(`Run ${teal('somewhere preview')} to keep previewing.`);
+            if (timer)
+                clearTimeout(timer);
+            await watcher.close().catch(() => { });
+            process.exit(0);
+        }
         finally {
             deploying = false;
             if (pendingChanged.size || pendingDeleted.size)
@@ -737,6 +915,11 @@ async function deployBatch(client, projectId, cwd, changed, deleted, draftId, ex
             info(dim('Your last working preview is still up. Fix and save again.'));
             return null;
         }
+        const finished = previewFinishedReason(err);
+        if (finished) {
+            // Not a failed save — the preview itself is over. The loop stops on it.
+            throw new PreviewFinishedError(finished);
+        }
         console.log(`${dim(stamp())} ${label} ${red('✗ failed')} ${dim(`(${secs}s)`)}`);
         error(err instanceof Error ? err.message : String(err));
         return null;