run402 3.5.3 → 3.5.5

package/lib/core.mjs

@@ -0,0 +1,122 @@
+import { importArchiveToCore } from "#sdk/node";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { assertKnownFlags, flagValue, hasHelp, normalizeArgv, positionalArgs } from "./argparse.mjs";
+
+const HELP = `run402 core — Local Run402 Core commands
+
+Usage:
+  run402 core projects import <archive-path> --name <project-name> [options]
+
+Options:
+  --name <name>             New Core project name (default imported-project)
+  --env-file <path>         Env file satisfying required archive secrets.
+  --secret KEY=VALUE        Inline secret value; repeatable. Overrides --env-file.
+  --core-url <url>          Core gateway URL (default RUN402_CORE_URL or http://127.0.0.1:4020)
+  --dry-run                 Verify and plan without creating a Core project.
+  --require-runnable        Block import unless required secrets are supplied.
+  --json                    Emit final JSON.
+  --json-stream             Emit NDJSON progress events and final result event.
+`;
+
+const FLAG_VALUES = ["--name", "--env-file", "--secret", "--core-url"];
+const FLAGS = new Set([...FLAG_VALUES, "--dry-run", "--require-runnable", "--json", "--json-stream", "--help", "-h"]);
+
+export async function run(sub, args = []) {
+  const all = [sub, ...args].filter(Boolean);
+  if (hasHelp(all)) {
+    console.log(HELP);
+    return;
+  }
+  if (sub !== "projects") {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 core projects import <archive-path> [options]" });
+  }
+  const action = args[0];
+  if (action === "import") return importProject(args.slice(1));
+  fail({ code: "BAD_USAGE", message: "Usage: run402 core projects import <archive-path> [options]" });
+}
+
+async function importProject(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  assertKnownFlags(args, [...FLAGS], FLAG_VALUES);
+  const archivePath = positionalArgs(args, FLAG_VALUES)[0];
+  if (!archivePath) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 core projects import <archive-path> --name <project-name> [options]" });
+  }
+  const jsonStream = args.includes("--json-stream");
+  const secretValues = parseSecrets(args);
+  const name = flagValue(args, "--name") ?? "imported-project";
+  const coreUrl = flagValue(args, "--core-url") ?? undefined;
+  const startedEvent = {
+    event: "core_archive_import_started",
+    stage: "verify",
+    resource_type: "project_archive",
+    resource_id: archivePath,
+    status: "running",
+    completed_units: 0,
+    total_units: 1,
+    code: null,
+    message: "Verifying archive locally before Core import.",
+    next_action: { type: "none" },
+    retryable: false,
+    context: { archive_path: archivePath, core_url: coreUrl ?? null, project_name: name },
+  };
+  if (jsonStream) console.log(JSON.stringify(startedEvent));
+  try {
+    const result = await importArchiveToCore({
+      archivePath,
+      name,
+      coreUrl,
+      envFile: flagValue(args, "--env-file") ?? undefined,
+      secretValues,
+      dryRun: args.includes("--dry-run"),
+      requireRunnable: args.includes("--require-runnable"),
+    });
+    if (jsonStream) {
+      console.log(JSON.stringify({
+        event: "core_archive_import_complete",
+        stage: "complete",
+        resource_type: "project_archive",
+        resource_id: archivePath,
+        status: result.status,
+        completed_units: result.status === "imported" || result.status === "dry_run" ? 1 : 0,
+        total_units: 1,
+        code: firstDiagnosticCode(result),
+        message: `Core archive import status: ${result.status}`,
+        next_action: result.next_action,
+        retryable: result.status === "failed" && result.diagnostics.some((d) => d.retryable),
+        result,
+      }));
+    } else {
+      console.log(JSON.stringify({ ok: result.status === "imported" || result.status === "dry_run", import: result }, null, 2));
+    }
+    if (result.status !== "imported" && result.status !== "dry_run") process.exit(1);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function parseSecrets(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] !== "--secret") continue;
+    const value = args[i + 1];
+    if (!value || value.startsWith("--")) {
+      fail({ code: "BAD_FLAG", message: "--secret requires KEY=VALUE" });
+    }
+    const eq = value.indexOf("=");
+    if (eq <= 0) {
+      fail({ code: "BAD_FLAG", message: "--secret requires KEY=VALUE", details: { value } });
+    }
+    const key = value.slice(0, eq);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      fail({ code: "BAD_FLAG", message: `Invalid secret env var name: ${key}` });
+    }
+    out[key] = value.slice(eq + 1);
+    i += 1;
+  }
+  return out;
+}
+
+function firstDiagnosticCode(result) {
+  return result.diagnostics.find((d) => d.severity === "blocking")?.code ?? null;
+}

package/lib/deploy-v2.mjs

@@ -32,10 +32,11 @@ import {
 } from "#sdk/node";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { API, allowanceAuthHeaders, getActiveProjectId, resolveProjectId } from "./config.mjs";
+import { API, allowanceAuthHeaders, getActiveProjectId, resolveProjectId, isCoreApiTarget } from "./config.mjs";
 import { normalizeArgv } from "./argparse.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 import { withAutoApprove } from "./operator.mjs";
+import { editRequestAction, nextAction, retryAction } from "./next-actions.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
 
@@ -123,6 +124,11 @@ Routes:
   Routes activate atomically with the release. Direct /functions/v1/:name remains API-key protected.
   Runtime route failure codes: ROUTE_MANIFEST_LOAD_FAILED, ROUTED_INVOKE_WORKER_SECRET_MISSING, ROUTED_INVOKE_AUTH_FAILED, ROUTED_ROUTE_STALE, ROUTE_METHOD_NOT_ALLOWED, ROUTED_RESPONSE_TOO_LARGE.
 
+Function capabilities:
+  functions.replace.<name>.capabilities is an array of runtime capability strings.
+  Framework adapters use it for contracts such as "astro.ssr.v1"; omit it for
+  ordinary user-authored functions unless a documented helper requires it.
+
 Internationalization (routed functions):
   "i18n": { "defaultLocale": "en", "locales": ["en", "es", "fr"], "detect": ["cookie:wl_locale", "accept-language"] }
   Omit i18n to carry forward from base release; pass "i18n": null to clear the slice on the new release.
@@ -663,7 +669,16 @@ async function mergeAstroReleaseSlice(spec, dirArg) {
  * the manifest normalizer is the authority on shape validity, not this
  * best-effort extractor.
  */
-function collectManifestSourceFiles(spec, baseDir) {
+function isAstroSsrManifestFunction(entry) {
+  return (
+    entry &&
+    typeof entry === "object" &&
+    Array.isArray(entry.capabilities) &&
+    entry.capabilities.includes("astro.ssr.v1")
+  );
+}
+
+export function collectManifestSourceFiles(spec, baseDir) {
   const out = new Set();
   if (!spec || typeof spec !== "object") return [];
 
@@ -688,13 +703,20 @@ function collectManifestSourceFiles(spec, baseDir) {
     if (!map || typeof map !== "object") return;
     for (const entry of Object.values(map)) resolveEntryPath(entry);
   };
+  const eachFunctionValue = (map) => {
+    if (!map || typeof map !== "object") return;
+    for (const entry of Object.values(map)) {
+      if (isAstroSsrManifestFunction(entry)) continue;
+      resolveEntryPath(entry);
+    }
+  };
 
   const fns = spec.functions;
   if (fns && typeof fns === "object") {
-    eachValue(fns.replace);
+    eachFunctionValue(fns.replace);
     if (fns.patch && typeof fns.patch === "object") {
-      eachValue(fns.patch.put);
-      eachValue(fns.patch.set);
+      eachFunctionValue(fns.patch.put);
+      eachFunctionValue(fns.patch.set);
     }
   }
 
@@ -895,9 +917,10 @@ async function applyCmd(args) {
       credentials: githubActionsCredentials({ projectId: releaseSpec.project, apiBase: API }),
       disablePaidFetch: true,
     };
-  } else if (!loadLiveControlPlaneSession()) {
+  } else if (!isCoreApiTarget() && !loadLiveControlPlaneSession()) {
     // Aggressive early exit when no allowance is configured — unless a
-    // wallet-less human is deploying via their operator (control-plane) session.
+    // wallet-less human is deploying via their operator (control-plane) session
+    // or the active target is a self-hosted Core Gateway.
     allowanceAuthHeaders("/apply/v1/plans");
   }
 
@@ -908,6 +931,7 @@ async function applyCmd(args) {
         idempotencyKey,
         allowWarnings: opts.allowWarnings,
         allowWarningCodes: opts.allowWarningCodes,
+        target: isCoreApiTarget() ? "core" : "cloud",
       }),
     );
     console.log(JSON.stringify(result, null, 2));
@@ -939,66 +963,66 @@ const CI_DEPLOY_ERROR_GUIDANCE = {
   invalid_token: {
     hint: "Ensure the workflow has permissions: id-token: write and is running in the repository/branch linked with run402 ci link github.",
     next_actions: [
-      "Check the workflow permissions block includes id-token: write.",
-      "Re-run run402 ci link github if the repository, branch, or environment changed.",
+      nextAction("edit_request", { why: "Check the workflow permissions block includes id-token: write." }),
+      editRequestAction("run402 ci link github", "Re-link if the repository, branch, or environment changed."),
     ],
   },
   access_denied: {
     hint: "The OIDC token was valid, but no active Run402 CI binding allowed this workflow.",
     next_actions: [
-      "Run run402 ci list --project <prj_...> locally to inspect bindings.",
-      "Run run402 ci link github again for this repository/branch/environment.",
+      editRequestAction("run402 ci list --project <prj_...>", "Inspect active CI bindings for this project."),
+      editRequestAction("run402 ci link github", "Link this repository, branch, and environment to Run402."),
     ],
   },
   binding_revoked: {
     hint: "A matching CI binding existed but was revoked — most often because the project was transferred or handed to a new owner, which suspends the prior org's CI bindings.",
     next_actions: [
-      "Run run402 ci link github again from this repository to re-create the binding.",
-      "Do not run run402 ci set-asset-scopes — it returns 409 on a revoked binding.",
-      "Run run402 ci list --project <prj_...> locally to confirm the binding state.",
+      editRequestAction("run402 ci link github", "Re-create the CI binding from this repository."),
+      nextAction("edit_request", { why: "Do not run run402 ci set-asset-scopes; it returns 409 on a revoked binding." }),
+      editRequestAction("run402 ci list --project <prj_...>", "Confirm the binding state locally."),
     ],
   },
   event_not_allowed: {
     hint: "This binding only allows push and workflow_dispatch events in v1.",
     next_actions: [
-      "Trigger the workflow with push or workflow_dispatch.",
-      "Create a separate follow-up design before enabling PR deploy events.",
+      nextAction("retry", { why: "Trigger the workflow with push or workflow_dispatch." }),
+      nextAction("edit_request", { why: "Create a separate follow-up design before enabling PR deploy events." }),
     ],
   },
   repository_id_mismatch: {
     hint: "The GitHub repository id in the OIDC token does not match the linked binding.",
     next_actions: [
-      "Run run402 ci link github again from the current repository.",
-      "If automatic lookup fails, pass --repository-id with the numeric GitHub repository id.",
+      editRequestAction("run402 ci link github", "Re-link from the current repository."),
+      editRequestAction("run402 ci link github --repository-id <id>", "Pass the numeric GitHub repository id if automatic lookup fails."),
     ],
   },
   forbidden_spec_field: {
     hint: "CI deploys can deploy site/functions/database content and route declarations only when the binding includes covering route scopes.",
     next_actions: [
-      "Remove forbidden fields such as secrets, subdomains, or checks from the CI manifest.",
-      "Keep the normalized manifest small enough to avoid manifest_ref.",
+      nextAction("edit_request", { why: "Remove forbidden fields such as secrets, subdomains, or checks from the CI manifest." }),
+      nextAction("edit_request", { why: "Keep the normalized manifest small enough to avoid manifest_ref." }),
     ],
   },
   CI_ROUTE_SCOPE_DENIED: {
     hint: "This CI binding does not cover one or more route declarations in the deploy manifest.",
     next_actions: [
-      "Re-run run402 ci link github with --route-scope for every exact or prefix path the workflow may deploy.",
-      "Use exact scopes such as --route-scope /admin or prefix scopes such as --route-scope /api/*.",
-      "Run the deploy locally with run402 deploy apply for route changes outside the CI delegation.",
+      editRequestAction("run402 ci link github --route-scope <pattern>", "Add a CI route scope for every exact or prefix path the workflow may deploy."),
+      nextAction("edit_request", { why: "Use exact scopes such as --route-scope /admin or prefix scopes such as --route-scope /api/*." }),
+      editRequestAction("run402 deploy apply", "Run route changes locally when they are outside the CI delegation."),
     ],
   },
   forbidden_plan: {
     hint: "The gateway rejected this deploy plan for CI. Keep CI deploys to the allowed resources and re-link if policy changed.",
     next_actions: [
-      "Inspect the gateway error details for the rejected resource.",
-      "Run the deploy locally with run402 deploy apply for operations outside the CI allowlist.",
+      nextAction("edit_request", { why: "Inspect the gateway error details for the rejected resource." }),
+      editRequestAction("run402 deploy apply", "Run operations outside the CI allowlist locally."),
     ],
   },
   payment_required: {
     hint: "The project tier or payment state does not allow this CI deploy.",
     next_actions: [
-      "Run run402 tier status --project <prj_...> locally.",
-      "Renew or upgrade the project tier, then re-run the workflow.",
+      editRequestAction("run402 tier status --project <prj_...>", "Inspect project tier and payment state locally."),
+      editRequestAction("run402 tier set <tier>", "Renew or upgrade the project tier, then re-run the workflow."),
     ],
   },
 };
@@ -1032,18 +1056,22 @@ function enhanceDeployWarningError(err) {
       : code
         ? [code]
         : [];
-  const allowWarningAction = unacknowledgedCodes.length === 1
-    ? `Retry with \`--allow-warning ${unacknowledgedCodes[0]}\` only after reviewing that warning.`
-    : unacknowledgedCodes.length > 1
-      ? `Retry with one \`--allow-warning <code>\` per reviewed warning code: ${unacknowledgedCodes.join(", ")}.`
-      : "Retry with `--allow-warning <code>` only after reviewing the warning.";
+  const allowWarningCommand = unacknowledgedCodes.length > 0
+    ? `run402 deploy apply ${unacknowledgedCodes.map((warningCode) => `--allow-warning ${warningCode}`).join(" ")}`
+    : "run402 deploy apply --allow-warning <code>";
+  const allowWarningAction = editRequestAction(
+    allowWarningCommand,
+    unacknowledgedCodes.length > 0
+      ? `Retry only after reviewing warning code${unacknowledgedCodes.length === 1 ? "" : "s"}: ${unacknowledgedCodes.join(", ")}.`
+      : "Retry only after reviewing the warning code.",
+  );
   const defaultNextActions = [
     ...(affected.length > 0
-      ? [`Set or inspect affected secrets: ${Array.from(new Set(affected)).join(", ")}`]
+      ? [editRequestAction("run402 secrets set <project> <KEY> --stdin", `Set or inspect affected secrets: ${Array.from(new Set(affected)).join(", ")}`)]
       : []),
-    "Retry `run402 deploy apply` after resolving warnings.",
+    retryAction("run402 deploy apply", "Retry after resolving warnings."),
     allowWarningAction,
-    "Use `--allow-warnings` only when every warning was explicitly reviewed.",
+    editRequestAction("run402 deploy apply --allow-warnings", "Use only when every warning was explicitly reviewed."),
   ];
   enhanced.body = {
     ...existingBody,
@@ -1066,98 +1094,98 @@ const ROUTE_WARNING_GUIDANCE = {
   PUBLIC_ROUTED_FUNCTION: {
     hint: "A deploy route makes a function public same-origin browser ingress; direct /functions/v1/:name remains API-key protected.",
     next_actions: [
-      "Review application auth and authorization in the routed function.",
-      "Add CSRF protection for cookie-authenticated POST/PUT/PATCH/DELETE routes.",
-      "Implement CORS and OPTIONS explicitly when cross-origin callers are intended.",
-      "Retry with --allow-warnings only after the public ingress review is intentional.",
+      nextAction("edit_request", { why: "Review application auth and authorization in the routed function." }),
+      nextAction("edit_request", { why: "Add CSRF protection for cookie-authenticated POST/PUT/PATCH/DELETE routes." }),
+      nextAction("edit_request", { why: "Implement CORS and OPTIONS explicitly when cross-origin callers are intended." }),
+      retryAction("run402 deploy apply --allow-warnings", "Retry only after the public ingress review is intentional."),
     ],
   },
   ROUTE_TARGET_CARRIED_FORWARD: {
     hint: "A carried-forward route still points at a base-release function target.",
     next_actions: [
-      "Inspect the active release with run402 deploy release active.",
-      "Deploy routes.replace if the target should change in this release.",
+      editRequestAction("run402 deploy release active", "Inspect the active release."),
+      editRequestAction("run402 deploy apply --manifest <path>", "Deploy routes.replace if the target should change in this release."),
     ],
   },
   ROUTE_SHADOWS_STATIC_PATH: {
     hint: "A dynamic route shadows a static site path.",
     next_actions: [
-      "Inspect the warning details for affected static paths.",
-      "Inspect live routes with run402 deploy release active.",
-      "Retry with --allow-warnings only when dynamic shadowing is intentional.",
+      nextAction("edit_request", { why: "Inspect the warning details for affected static paths." }),
+      editRequestAction("run402 deploy release active", "Inspect live routes."),
+      retryAction("run402 deploy apply --allow-warnings", "Retry only when dynamic shadowing is intentional."),
     ],
   },
   WILDCARD_ROUTE_SHADOWS_STATIC_PATHS: {
     hint: "A prefix wildcard route shadows one or more static site paths.",
     next_actions: [
-      "Review affected route/static path details.",
-      "Split exact routes or move static paths if the shadowing is accidental.",
-      "Retry with --allow-warnings only when the wildcard shadowing is intentional.",
+      nextAction("edit_request", { why: "Review affected route/static path details." }),
+      nextAction("edit_request", { why: "Split exact routes or move static paths if the shadowing is accidental." }),
+      retryAction("run402 deploy apply --allow-warnings", "Retry only when the wildcard shadowing is intentional."),
     ],
   },
   METHOD_SPECIFIC_ROUTE_ALLOWS_GET_STATIC_FALLBACK: {
     hint: "A method-specific route allows static fallback for unmatched methods such as GET.",
     next_actions: [
-      "Confirm that static fallback for GET/HEAD is intended.",
-      "Add method coverage or static files deliberately.",
+      nextAction("edit_request", { why: "Confirm that static fallback for GET/HEAD is intended." }),
+      nextAction("edit_request", { why: "Add method coverage or static files deliberately." }),
     ],
   },
   WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS: {
     hint: "A wildcard function route only allows GET/HEAD, so POST/PUT/PATCH/DELETE paths under that prefix will be rejected before the function runs.",
     next_actions: [
-      "Add the mutation methods the routed function supports, such as POST.",
-      "Omit methods to allow every supported method when the route is an API surface.",
-      "Set acknowledge_readonly: true on an intentionally read-only GET/HEAD wildcard function route.",
-      "Use --allow-warning WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS only as a reviewed CLI escape hatch.",
+      nextAction("edit_request", { why: "Add the mutation methods the routed function supports, such as POST." }),
+      nextAction("edit_request", { why: "Omit methods to allow every supported method when the route is an API surface." }),
+      nextAction("edit_request", { why: "Set acknowledge_readonly: true on an intentionally read-only GET/HEAD wildcard function route." }),
+      retryAction("run402 deploy apply --allow-warning WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS", "Use only as a reviewed CLI escape hatch."),
     ],
   },
   ROUTE_TABLE_NEAR_LIMIT: {
     hint: "The route table is near the gateway/project limit.",
     next_actions: [
-      "Consolidate prefix routes where possible.",
-      "Remove stale route entries before adding more.",
+      nextAction("edit_request", { why: "Consolidate prefix routes where possible." }),
+      nextAction("edit_request", { why: "Remove stale route entries before adding more." }),
     ],
   },
   ROUTES_NOT_ENABLED: {
     hint: "Deploy-v2 web routes are not enabled for this project or environment; direct /functions/v1/:name remains protected and is not a browser-route substitute.",
     next_actions: [
-      "Deploy without the routes resource, or request route enablement for this project/environment.",
-      "Keep direct function invocation API-key protected; do not substitute it for same-origin browser routes.",
+      nextAction("edit_request", { why: "Deploy without the routes resource, or request route enablement for this project/environment." }),
+      nextAction("edit_request", { why: "Keep direct function invocation API-key protected; do not substitute it for same-origin browser routes." }),
     ],
   },
   STATIC_ALIAS_SHADOWS_STATIC_PATH: {
     hint: "A static route target shadows a direct static path at the same public URL.",
     next_actions: [
-      "Inspect the route pattern, target.file, and direct static path.",
-      "Confirm only when the static route target is intentional.",
+      nextAction("edit_request", { why: "Inspect the route pattern, target.file, and direct static path." }),
+      nextAction("edit_request", { why: "Confirm only when the static route target is intentional." }),
     ],
   },
   STATIC_ALIAS_RELATIVE_ASSET_RISK: {
     hint: "Relative asset URLs inside the target HTML may resolve differently at the static route target URL.",
     next_actions: [
-      "Inspect the target HTML for relative asset references.",
-      "Use absolute asset URLs or confirm only when the alternate URL is intentional.",
+      nextAction("edit_request", { why: "Inspect the target HTML for relative asset references." }),
+      nextAction("edit_request", { why: "Use absolute asset URLs or confirm only when the alternate URL is intentional." }),
     ],
   },
   STATIC_ALIAS_DUPLICATE_CANONICAL_URL: {
     hint: "Both the static route target URL and the target file URL may be publicly reachable.",
     next_actions: [
-      "Decide which URL should be canonical.",
-      "Update links/canonical tags or accept the duplicate public URL intentionally.",
+      nextAction("edit_request", { why: "Decide which URL should be canonical." }),
+      nextAction("edit_request", { why: "Update links/canonical tags or accept the duplicate public URL intentionally." }),
     ],
   },
   STATIC_ALIAS_EXTENSIONLESS_NON_HTML: {
     hint: "An extensionless static route target points at a non-HTML file.",
     next_actions: [
-      "Check that the extensionless route is meant to serve that content type.",
-      "Prefer extensionless static route targets for HTML pages.",
+      nextAction("edit_request", { why: "Check that the extensionless route is meant to serve that content type." }),
+      nextAction("edit_request", { why: "Prefer extensionless static route targets for HTML pages." }),
     ],
   },
   STATIC_ALIAS_TABLE_NEAR_LIMIT: {
     hint: "Static route targets count toward the route table limit.",
     next_actions: [
-      "Consolidate manual static route targets where possible.",
-      "Avoid one route entry per page for large sites until framework-scale Web Output support exists.",
+      nextAction("edit_request", { why: "Consolidate manual static route targets where possible." }),
+      nextAction("edit_request", { why: "Avoid one route entry per page for large sites until framework-scale Web Output support exists." }),
     ],
   },
 };

package/lib/doctor-source-scan.mjs

@@ -29,7 +29,7 @@
  * summary. Wired into `run402 deploy` pre-flight as a deploy-failing
  * gate for the error severities; non-blocking for warning severities.
  *
- * @see openspec/changes/auth-aware-ssr/specs/functions-sdk-auth-model
+ * @see the auth-aware-ssr OpenSpec change (functions-sdk-auth-model)
  */
 
 import { readdirSync, readFileSync, statSync } from "node:fs";

package/lib/functions.mjs

@@ -3,6 +3,7 @@ import { findProject, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag, validateRegularFile } from "./argparse.mjs";
+import { cliCommandAction } from "./next-actions.mjs";
 
 const FUNCTION_LOG_REQUEST_ID_RE = /^req_[A-Za-z0-9_-]{4,128}$/;
 const ISO_DATE_TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
@@ -541,7 +542,7 @@ async function rebuild(projectId, args = []) {
         code: "CANNOT_REBUILD_UNLOCKED_DEPS",
         message: err.body.error || err.body.message || "Function was deployed before dependency locking.",
         hint: UNLOCKED_DEPS_HINT,
-        next_actions: [`run402 functions deploy ${projectId} ${name} --file <file>`],
+        next_actions: [cliCommandAction("deploy", `run402 functions deploy ${projectId} ${name} --file <file>`, "Redeploy the function once so Run402 can lock dependencies for future rebuilds.")],
         retryable: false,
         safe_to_retry: false,
       });

package/lib/init.mjs

@@ -1,4 +1,4 @@
-import { readAllowance, saveAllowance, loadKeyStore, configDir } from "./config.mjs";
+import { readAllowance, saveAllowance, loadKeyStore, configDir, configureApiBase } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { fail } from "./sdk-errors.mjs";
 import { setTierAction, deployAction } from "./next-actions.mjs";
@@ -15,6 +15,9 @@ const HELP = `run402 init — Set up allowance, funding, and check tier status
 
 Usage:
   run402 init                Set up with x402 (Base Sepolia) — default
+  run402 init --api-base <url>
+                             Configure a Run402 Core/API target for the active
+                             profile without setting up Cloud payment.
   run402 init mpp            Set up with MPP (Tempo Moderato)
   run402 init <rail> --switch-rail
                              Switch the persisted payment rail to <rail>.
@@ -23,6 +26,9 @@ Usage:
                              silently flipping billing networks.
 
 Options:
+  --api-base <url> Configure the active profile to use this API base. Use this
+                  for a self-hosted Run402 Core Gateway, e.g.
+                  http://my-core:4020.
   --switch-rail   Confirm switching the persisted payment rail. Re-running
                   init with the SAME rail as the existing allowance is always
                   idempotent and does not need this flag.
@@ -46,6 +52,61 @@ Run this once to get started, or again to check your setup.
 
 function short(addr) { return addr.slice(0, 6) + "..." + addr.slice(-4); }
 
+function parseApiBaseFlag(args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--api-base") {
+      const value = args[i + 1];
+      if (value === undefined || String(value).startsWith("--")) {
+        fail({
+          code: "BAD_USAGE",
+          message: "--api-base requires a value.",
+          details: { flag: "--api-base" },
+        });
+      }
+      return { value, args: [...args.slice(0, i), ...args.slice(i + 2)] };
+    }
+    if (typeof arg === "string" && arg.startsWith("--api-base=")) {
+      const value = arg.slice("--api-base=".length);
+      if (!value) {
+        fail({
+          code: "BAD_USAGE",
+          message: "--api-base requires a non-empty value.",
+          details: { flag: "--api-base" },
+        });
+      }
+      return { value, args: [...args.slice(0, i), ...args.slice(i + 1)] };
+    }
+  }
+  return { value: null, args };
+}
+
+function sameOrigin(a, b) {
+  try {
+    return new URL(a).origin === new URL(b).origin;
+  } catch {
+    return false;
+  }
+}
+
+async function detectTarget(apiBase) {
+  try {
+    const health = await getSdk({ apiBase, disablePaidFetch: true, authMode: "none" }).service.health();
+    const kind = health && typeof health === "object" && health.mode === "core"
+      ? "core"
+      : sameOrigin(apiBase, "https://api.run402.com") ? "cloud" : "core";
+    return {
+      kind,
+      health_status: typeof health?.status === "string" ? health.status : "ok",
+    };
+  } catch (err) {
+    return {
+      kind: sameOrigin(apiBase, "https://api.run402.com") ? "cloud" : "core",
+      health_error: errorMessage(err),
+    };
+  }
+}
+
 function errorMessage(err) {
   if (err?.body && typeof err.body === "object") return err.body.message || err.body.error || err.message;
   return err?.message || String(err);
@@ -67,6 +128,50 @@ export async function run(args = []) {
 
   if (args.includes("--help") || args.includes("-h")) { console.log(HELP); process.exit(0); }
 
+  const parsedApiBase = parseApiBaseFlag(args);
+  if (parsedApiBase.value) {
+    if (parsedApiBase.args.some((arg) => typeof arg === "string" && !arg.startsWith("--"))) {
+      fail({
+        code: "BAD_USAGE",
+        message: "run402 init --api-base cannot be combined with a payment rail.",
+        hint: "Run `run402 init --api-base=http://my-core:4020` for Core, or `run402 init` for Run402 Cloud.",
+      });
+    }
+    const CONFIG_DIR = configDir();
+    const detected = await detectTarget(parsedApiBase.value);
+    const config = configureApiBase(parsedApiBase.value, {
+      target_kind: detected.kind,
+      ...(detected.health_status ? { health_status: detected.health_status } : {}),
+      ...(detected.health_error ? { health_error: detected.health_error } : {}),
+    });
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    console.error("");
+    console.error(`  ${"Config".padEnd(10)} ${CONFIG_DIR}`);
+    console.error(`  ${"API base".padEnd(10)} ${config.api_base}`);
+    console.error(`  ${"Target".padEnd(10)} ${config.target_kind}`);
+    if (detected.health_status) console.error(`  ${"Health".padEnd(10)} ${detected.health_status}`);
+    if (detected.health_error) console.error(`  ${"Health".padEnd(10)} ${detected.health_error}`);
+    console.error("");
+    const summary = {
+      config_dir: CONFIG_DIR,
+      api_base: config.api_base,
+      api_base_source: "profile",
+      target: {
+        kind: config.target_kind,
+        ...(config.health_status ? { health_status: config.health_status } : {}),
+        ...(config.health_error ? { health_error: config.health_error } : {}),
+      },
+      payment_required: config.target_kind === "cloud",
+      next_actions: [{
+        type: "create_project",
+        command: 'run402 projects provision --name "my-app"',
+      }],
+      next_step: 'run402 projects provision --name "my-app"',
+    };
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+
   // Resolve once for this invocation — reflects the active wallet/profile that
   // cli.mjs published to RUN402_WALLET before this module loaded.
   const CONFIG_DIR = configDir();