@solcreek/cli 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @solcreek/cli
 
+## 0.4.5
+
+### Features
+
+- **`creek deploy --dry-run`** — new flag that reports a plan without
+  executing: resolved config source, detected framework, build command,
+  build output, bindings, cron/queue triggers, auth status, and the
+  target type (sandbox vs production). No network calls, no file
+  uploads, no ToS prompt, no build. Pair with `--json` for a
+  machine-readable plan. Safe to call from an AI coding agent that
+  wants to understand `creek deploy` behavior before running it.
+  Unsupported modes (`--template`, `--from-github`, repo-url) short-
+  circuit with a clear "not yet supported" message.
+
+- **Static-site sandbox fast path** — `creek deploy` in a directory
+  that contains only `index.html` (no `package.json`) now works. The
+  SDK falls back to the `index.html` source and `deploySandbox`
+  recognizes that case and delegates straight to `deployDirectory`,
+  which uploads the cwd as-is. Previously crashed with an ENOENT on
+  package.json. The simplest possible onboarding now works end-to-end:
+
+      mkdir hello && cd hello
+      echo '<h1>Hi</h1>' > index.html
+      npx creek deploy
+
+- **Astro framework support** — any Astro 3+ project (SPA, SSG, MDX,
+  content collections) auto-detects and builds via `astro build`.
+  Tested end-to-end against Astro 6 + Tailwind 4 + sharp image
+  optimization (`jiseeeh/serene-ink` blog theme). Via the existing
+  repo-URL flow, `npx creek deploy https://github.com/user/astro-theme`
+  now works with zero Creek-side configuration.
+
+- **Richer `creek deploy --help`** — `meta.description` and every arg
+  description rewritten to spell out sandbox-vs-production behavior,
+  auto-detection chain, safety notes around `--dry-run`, and example
+  invocations. Primary audience is AI agents reading `--help` output
+  on a cold paste, which shows up concretely as better self-description
+  in the first tool call.
+
+### Fixes
+
+- `NO_PROJECT_BREADCRUMBS`, the sandbox-status not-found hint, and
+  deploy.ts error paths now point to
+  `creek deploy --template landing` instead of the non-existent
+  `--demo` flag. Matching doc scrub across README, docs, llms.txt,
+  and the pricing page.
+
 ## 0.4.4
 
 ### Features

package/README.md

@@ -6,7 +6,7 @@ Deploy to the edge in seconds. No account required.
 [![License](https://img.shields.io/badge/license-Apache%202.0-green)](https://github.com/solcreek/creek/blob/main/LICENSE)
 
 ```bash
-npx creek deploy --demo
+npx creek deploy --template landing
 # Live in 8.3s -> https://a1b2c3d4.creeksandbox.com
 ```
 
@@ -28,12 +28,14 @@ npx creek deploy
 
 ## Quick Start
 
-### Deploy a demo (no account needed)
+### Start from a template (no account needed)
 
 ```bash
-creek deploy --demo
+creek deploy --template landing
 ```
 
+Clones a ready-made Vite + React landing page, builds it, and deploys it to a 60-minute sandbox URL — all in one command. The code is yours to edit.
+
 ### Deploy your project
 
 ```bash
@@ -61,7 +63,8 @@ creek deploy https://github.com/user/repo/tree/main/packages/app
 | Command | Description |
 |---------|-------------|
 | `creek deploy [dir]` | Deploy project, directory, or repo URL |
-| `creek deploy --demo` | Deploy a sample site instantly |
+| `creek deploy --template <name>` | Clone + build + deploy a named template |
+| `creek deploy --dry-run` | Show the deploy plan without executing (agent-safe) |
 | `creek projects` | List your projects |
 | `creek deployments` | List deployments for a project |
 | `creek status` | Show current project status |
@@ -154,7 +157,7 @@ Creek auto-detects and configures the build for:
 
 | Mode | Trigger | Auth Required | TTL |
 |------|---------|:-------------:|-----|
-| **Demo** | `--demo` flag | No | 60 min |
+| **Template** | `--template <name>` | No | 60 min |
 | **Sandbox** | No `creek.toml` | No | 60 min |
 | **Production** | Has `creek.toml` + token | Yes | Permanent |
 

package/dist/commands/deploy.d.ts

@@ -44,6 +44,11 @@ export declare const deployCommand: import("citty").CommandDef<{
         description: string;
         default: false;
     };
+    "dry-run": {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
 }>;
 export interface CliDeployment {
     id: string;

package/dist/commands/deploy.js

@@ -30,51 +30,200 @@ function assetSummary(fileList) {
         .map(([ext, n]) => `${n} ${ext}`);
     return parts.join(", ");
 }
+/**
+ * Dry-run handler: describes what `creek deploy` would do without
+ * executing. No network calls, no file uploads, no builds, no ToS
+ * prompts. Safe to call from an AI agent that wants to understand
+ * the deploy plan before running it.
+ *
+ * Always exits 0 — a dry-run is "successful" even when no project is
+ * found, because the goal is to report state, not enforce it.
+ */
+async function dryRunPlan(cwd, args, jsonMode) {
+    // Unsupported modes — report and return cleanly
+    const unsupportedMode = args.template ? "template"
+        : args["from-github"] ? "from-github"
+            : (typeof args.dir === "string" && isRepoUrl(args.dir)) ? "repo-url"
+                : null;
+    if (unsupportedMode) {
+        if (jsonMode) {
+            jsonOutput({
+                mode: "dry-run",
+                supported: false,
+                unsupportedMode,
+                message: `Dry-run is not yet supported for --${unsupportedMode} deploys`,
+                hint: `Run without --dry-run to execute, or inspect the command docs with --help`,
+            }, 0, []);
+            return;
+        }
+        consola.log(`\n  \x1b[2m[dry-run]\x1b[0m Dry-run is not yet supported for --${unsupportedMode} deploys.\n`);
+        consola.log(`  Run without --dry-run to execute, or inspect the command docs with --help.\n`);
+        return;
+    }
+    // Main case: resolve config in cwd
+    let resolved = null;
+    try {
+        resolved = resolveConfig(cwd);
+    }
+    catch (err) {
+        if (!(err instanceof ConfigNotFoundError))
+            throw err;
+    }
+    const token = getToken();
+    const authenticated = !!token;
+    // If no config, check build-output fallback
+    let buildOutputFallback = null;
+    if (!resolved) {
+        for (const dir of ["dist", "build", "out", ".output/public"]) {
+            if (existsSync(resolve(cwd, dir))) {
+                buildOutputFallback = dir;
+                break;
+            }
+        }
+    }
+    const wouldDeploy = !!(resolved || buildOutputFallback);
+    const targetType = authenticated ? "production" : "sandbox";
+    const bindings = resolved
+        ? resolvedConfigToBindingRequirements(resolved).map((b) => ({
+            name: b.bindingName,
+            type: b.type,
+        }))
+        : [];
+    const plan = {
+        mode: "dry-run",
+        supported: true,
+        cwd,
+        authenticated,
+        target: {
+            type: targetType,
+            description: targetType === "production"
+                ? "Your team's production slot (permanent URL via creek.toml)"
+                : "Free 60-minute sandbox (no signup required)",
+        },
+        config: resolved
+            ? {
+                source: resolved.source,
+                projectName: resolved.projectName,
+                framework: resolved.framework,
+                buildCommand: resolved.buildCommand,
+                buildOutput: resolved.buildOutput,
+                cron: resolved.cron,
+                queue: resolved.queue,
+            }
+            : null,
+        buildOutputFallback,
+        bindings,
+        wouldDeploy,
+        sideEffects: {
+            networkCalls: false,
+            fileUploads: false,
+            buildExecuted: false,
+            tosPromptShown: false,
+        },
+        nextStep: wouldDeploy
+            ? "Run without --dry-run to execute: npx creek deploy"
+            : "No project config or build output found. Run `creek init` or `npm create vite@latest` first.",
+    };
+    if (jsonMode) {
+        jsonOutput(plan, 0, []);
+        return;
+    }
+    // Human-readable plan
+    consola.log("\n  \x1b[2m[dry-run]\x1b[0m No deploy will execute. No network calls. No uploads.\n");
+    consola.log(`  cwd:              ${cwd}`);
+    consola.log(`  Auth status:      ${authenticated ? "✓ signed in" : "✗ not signed in"}`);
+    consola.log(`  Deploy target:    ${targetType} — ${plan.target.description}`);
+    if (resolved) {
+        consola.log(`  Detected:         ${formatDetectionSummary(resolved)}`);
+        consola.log(`  Project name:     ${resolved.projectName}`);
+        if (resolved.framework) {
+            consola.log(`  Framework:        ${resolved.framework}`);
+        }
+        consola.log(`  Build command:    ${resolved.buildCommand}`);
+        consola.log(`  Build output:     ${resolved.buildOutput}`);
+        if (bindings.length > 0) {
+            consola.log(`  Bindings:         ${bindings.map((b) => `${b.name} (${b.type})`).join(", ")}`);
+        }
+        if (resolved.cron.length > 0) {
+            consola.log(`  Cron triggers:    ${resolved.cron.join(", ")}`);
+        }
+        if (resolved.queue) {
+            consola.log(`  Queue trigger:    enabled`);
+        }
+        if (resolved.unsupportedBindings.length > 0) {
+            consola.log(`  Unsupported:      ${resolved.unsupportedBindings
+                .map((b) => `${b.name} (${b.type})`)
+                .join(", ")} — would be skipped`);
+        }
+    }
+    else if (buildOutputFallback) {
+        consola.log(`  Detected:         prebuilt assets in ${buildOutputFallback}/ (no creek.toml, no wrangler config)`);
+    }
+    else {
+        consola.log(`  Detected:         nothing — no creek.toml, no wrangler config, no dist/build/out/.output/public/`);
+    }
+    consola.log(`\n  Next step:        ${plan.nextStep}\n`);
+}
 export const deployCommand = defineCommand({
     meta: {
         name: "deploy",
-        description: "Deploy the current project to Creek",
+        description: "Deploy the current project to Creek. Signed-in: deploys to your team's production slot. Not signed in: creates a free 60-minute sandbox URL (no signup). Auto-detects framework from creek.toml, wrangler files, package.json, or index.html. Safe to run from an AI coding agent — use --dry-run first to inspect the plan without executing.",
     },
     args: {
         dir: {
             type: "positional",
-            description: "Directory to deploy (default: current directory)",
+            description: "Directory to deploy (default: current directory). Also accepts a GitHub repo URL to clone-and-deploy.",
             required: false,
         },
         "skip-build": {
             type: "boolean",
-            description: "Skip the build step",
+            description: "Skip the build step — upload existing build output as-is. Useful when CI already built the artifact.",
+            default: false,
+        },
+        "dry-run": {
+            type: "boolean",
+            description: "Show what would be deployed without doing it: resolved config, detected framework, bindings, target URL, auth status. No network calls, no file uploads. Pair with --json for machine-readable plan output. Safe for agents.",
             default: false,
         },
         ...globalArgs,
         template: {
             type: "string",
-            description: "Deploy a template (e.g., landing, blog, todo)",
+            description: "Deploy a named template (e.g., landing, blog, todo). Combine with --data to pass template params.",
             required: false,
         },
         data: {
             type: "string",
-            description: "JSON data for template params (used with --template)",
+            description: "JSON string of template parameters (used with --template). Example: --data '{\"title\":\"Hello\"}'",
             required: false,
         },
         path: {
             type: "string",
-            description: "Subdirectory within repo to deploy (for monorepos)",
+            description: "Subdirectory within the repo to deploy, for monorepos. Example: --path apps/web",
             required: false,
         },
         "from-github": {
             type: "boolean",
-            description: "Skip local build; trigger a deploy of the latest commit on the project's production branch via its GitHub connection",
+            description: "Skip local build; trigger a remote deploy of the latest commit on the project's production branch via its GitHub connection.",
             default: false,
         },
         project: {
             type: "string",
-            description: "Target project slug or UUID (required with --from-github when not run inside a project directory)",
+            description: "Target project slug or UUID. Required with --from-github when not run inside a project directory.",
             required: false,
         },
     },
     async run({ args }) {
         const jsonMode = resolveJsonMode(args);
+        // --- Dry-run short-circuit ---
+        // No ToS prompt, no network, no file uploads, no builds. Pure config
+        // resolution + plan output. Safe to call from an AI agent that wants
+        // to understand what `creek deploy` would do before running it.
+        if (args["dry-run"]) {
+            const dryCwd = args.dir && typeof args.dir === "string" && !isRepoUrl(args.dir)
+                ? resolve(args.dir)
+                : process.cwd();
+            return await dryRunPlan(dryCwd, args, jsonMode);
+        }
         // --- Ensure ToS accepted ---
         const autoConfirm = shouldAutoConfirm(args);
         const tos = await ensureTosAccepted(autoConfirm);
@@ -490,9 +639,39 @@ async function deployDirectory(dir, jsonMode, tos) {
 // Sandbox deploy — auto-detect framework, build, deploy
 // ============================================================================
 async function deploySandbox(cwd, skipBuild, jsonMode = false, resolved, tos) {
-    const framework = resolved?.framework ?? detectFramework(JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8")));
+    // Static-site fast path: when resolveConfig fell back to index.html, the cwd
+    // has no build step and may have no package.json. Delegate to deployDirectory
+    // which just uploads the cwd as-is. This handles the simplest possible
+    // onboarding:
+    //     mkdir test && cd test
+    //     echo '<h1>Hi</h1>' > index.html
+    //     npx creek deploy
+    if (resolved?.source === "index.html") {
+        return deployDirectory(cwd, jsonMode, tos);
+    }
+    // Framework path: package.json should exist because resolveConfig picked a
+    // framework from package.json, wrangler files, or creek.toml. Guard anyway
+    // so we fail with a helpful message instead of an ENOENT stack trace.
+    const pkgJsonPath = join(cwd, "package.json");
+    if (!existsSync(pkgJsonPath)) {
+        const message = `Expected package.json in ${cwd} but none found.`;
+        if (jsonMode) {
+            jsonOutput({
+                ok: false,
+                error: "no_package_json",
+                message,
+                hint: "Run `npx creek deploy ./dist` to deploy a prebuilt directory, or `npx creek deploy --template landing` to start from a template.",
+            }, 1, NO_PROJECT_BREADCRUMBS);
+            return;
+        }
+        consola.error(message);
+        consola.info("  Run `npx creek deploy ./dist` to deploy a prebuilt directory instead,");
+        consola.info("  or `npx creek deploy --template landing` to start from a template.");
+        process.exit(1);
+    }
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+    const framework = resolved?.framework ?? detectFramework(pkg);
     // Detect Next.js mode (static vs opennext SSR)
-    const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8"));
     const nextjsMode = framework === "nextjs" ? detectNextjsMode(pkg, cwd) : null;
     const monorepo = detectMonorepo(cwd);
     section("Detect");

package/dist/commands/status.js

@@ -33,7 +33,7 @@ async function sandboxStatus(sandboxId, jsonMode) {
     if (!res.ok) {
         if (jsonMode)
             jsonOutput({ ok: false, error: "not_found", message: "Sandbox not found" }, 1, [
-                { command: "creek deploy --demo", description: "Deploy a new sandbox" },
+                { command: "creek deploy --template landing", description: "Deploy a new sandbox from a template" },
             ]);
         consola.error("Sandbox not found. It may have expired.");
         process.exit(1);

package/dist/utils/output.js

@@ -50,6 +50,6 @@ export const AUTH_BREADCRUMBS = [
 ];
 export const NO_PROJECT_BREADCRUMBS = [
     { command: "creek init", description: "Initialize creek.toml in current directory" },
-    { command: "creek deploy --demo", description: "Deploy a sample site to try Creek" },
+    { command: "creek deploy --template landing", description: "Start from a ready-made Vite + React landing page" },
 ];
 //# sourceMappingURL=output.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solcreek/cli",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "CLI for the Creek deployment platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "miniflare": "^4.20260317.3",
     "smol-toml": "^1.3.1",
     "ws": "^8.20.0",
-    "@solcreek/sdk": "0.4.1"
+    "@solcreek/sdk": "0.4.2"
   },
   "devDependencies": {
     "@testing-library/dom": "^10.4.1",