@m-kopa/launchpad-cli 0.76.0 → 0.78.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/dist/bundle/upload.d.ts +16 -0
  3. package/dist/bundle/upload.d.ts.map +1 -1
  4. package/dist/cli.js +3415 -597
  5. package/dist/commands/admin-cli-sessions.d.ts +6 -0
  6. package/dist/commands/admin-cli-sessions.d.ts.map +1 -0
  7. package/dist/commands/admin.d.ts.map +1 -1
  8. package/dist/commands/agreement.d.ts +44 -0
  9. package/dist/commands/agreement.d.ts.map +1 -0
  10. package/dist/commands/app-lints.d.ts +14 -0
  11. package/dist/commands/app-lints.d.ts.map +1 -0
  12. package/dist/commands/deploy-flags.d.ts +2 -0
  13. package/dist/commands/deploy-flags.d.ts.map +1 -1
  14. package/dist/commands/deploy.d.ts.map +1 -1
  15. package/dist/commands/destroy.d.ts +36 -0
  16. package/dist/commands/destroy.d.ts.map +1 -1
  17. package/dist/commands/disable.d.ts +42 -0
  18. package/dist/commands/disable.d.ts.map +1 -0
  19. package/dist/commands/init.d.ts +10 -0
  20. package/dist/commands/init.d.ts.map +1 -1
  21. package/dist/commands/login.d.ts +4 -1
  22. package/dist/commands/login.d.ts.map +1 -1
  23. package/dist/commands/status.d.ts +13 -1
  24. package/dist/commands/status.d.ts.map +1 -1
  25. package/dist/commands/validate.d.ts.map +1 -1
  26. package/dist/deploy/preflight.d.ts +134 -0
  27. package/dist/deploy/preflight.d.ts.map +1 -0
  28. package/dist/deploy/verify-deploy.d.ts.map +1 -1
  29. package/dist/destroy-failure.d.ts +23 -0
  30. package/dist/destroy-failure.d.ts.map +1 -0
  31. package/dist/dispatcher.d.ts.map +1 -1
  32. package/dist/http/api-client.d.ts +16 -2
  33. package/dist/http/api-client.d.ts.map +1 -1
  34. package/dist/http/error-envelope.d.ts +13 -1
  35. package/dist/http/error-envelope.d.ts.map +1 -1
  36. package/dist/http/errors.d.ts +18 -0
  37. package/dist/http/errors.d.ts.map +1 -1
  38. package/dist/scaffold/react-api-starter-files.d.ts +7 -0
  39. package/dist/scaffold/react-api-starter-files.d.ts.map +1 -0
  40. package/dist/scaffold/react-api-starter.d.ts +26 -0
  41. package/dist/scaffold/react-api-starter.d.ts.map +1 -0
  42. package/dist/scaffold/secure-api-template.d.ts +57 -0
  43. package/dist/scaffold/secure-api-template.d.ts.map +1 -0
  44. package/dist/version.d.ts +1 -1
  45. package/package.json +2 -2
  46. package/skills/launchpad-content-pr/SKILL.md +48 -7
  47. package/skills/launchpad-deploy/SKILL.md +240 -10
  48. package/skills/launchpad-deploy-status/SKILL.md +111 -9
  49. package/skills/launchpad-destroy/SKILL.md +41 -8
  50. package/skills/launchpad-identity/SKILL.md +31 -1
  51. package/skills/launchpad-ingest/SKILL.md +11 -6
  52. package/skills/launchpad-integration-contract/SKILL.md +1 -1
  53. package/skills/launchpad-onboard/SKILL.md +21 -1
  54. package/skills/launchpad-report/SKILL.md +1 -1
  55. package/skills/launchpad-status/SKILL.md +13 -5
@@ -10,6 +10,16 @@ export declare class UnauthenticatedError extends Error {
10
10
  export declare class ForbiddenError extends Error {
11
11
  readonly code: "forbidden";
12
12
  }
13
+ /** Stable process exit for a server-enforced access agreement (A2-07). */
14
+ export declare const EXIT_AGREEMENT_REQUIRED = 43;
15
+ /** 403 `agreement_required`: the bot wants a current access agreement
16
+ * acceptance before this mutation. Subclasses ForbiddenError so callers
17
+ * that only know ForbiddenError still print the server message. */
18
+ export declare class AgreementRequiredError extends ForbiddenError {
19
+ readonly reason: string;
20
+ readonly version: string | null;
21
+ constructor(message: string, reason: string, version: string | null);
22
+ }
13
23
  /** 404 — the bot returned not-found. Distinct from UnauthenticatedError
14
24
  * so the CLI doesn't suggest re-login when the slug is just unknown. */
15
25
  export declare class NotFoundError extends Error {
@@ -47,6 +57,14 @@ export declare class ApiError extends Error {
47
57
  readonly envelope: StructuredErrorEnvelope;
48
58
  constructor(envelope: StructuredErrorEnvelope);
49
59
  }
60
+ /** HTTP 503 `revocation_unavailable` (audit finding XP-15). The bot could
61
+ * not read its CLI session revocation store, so it refused the request
62
+ * before running it. The session itself is not the problem: `launchpad
63
+ * login` does not help, a retry after `retryAfterSec` usually does. */
64
+ export declare class RevocationUnavailableError extends ApiError {
65
+ readonly retryAfterSec: number;
66
+ constructor(envelope: StructuredErrorEnvelope, retryAfterSec: number);
67
+ }
50
68
  /** Network failure, JSON parse failure, anything that wasn't
51
69
  * actually a response. */
52
70
  export declare class TransportError extends Error {
@@ -1 +1 @@
1
- {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/http/errors.ts"],"names":[],"mappings":"AAIA;;2DAE2D;AAC3D,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;CAC5C;AAED;;uCAEuC;AACvC,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;CACtC;AAED;yEACyE;AACzE,qBAAa,aAAc,SAAQ,KAAK;IAIT,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM;IAHzD,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IAErC,8EAA8E;gBAClE,OAAO,EAAE,MAAM,EAAW,UAAU,CAAC,EAAE,MAAM,YAAA;CAG1D;AAED,uEAAuE;AACvE,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,gFAAgF;AAChF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAU;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAM3C;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAE7B,2EAA2E;AAC3E,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,SAAS,EAAG,WAAW,CAAU;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC,YAAY,CAAC,CAAC;IAC3D,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;gBAE/B,QAAQ,EAAE,uBAAuB;CAgB9C;AAED;2BAC2B;AAC3B,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;CAC5C"}
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/http/errors.ts"],"names":[],"mappings":"AAIA;;2DAE2D;AAC3D,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;CAC5C;AAED;;uCAEuC;AACvC,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;CACtC;AAED,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;oEAEoE;AACpE,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;CAMpE;AAED;yEACyE;AACzE,qBAAa,aAAc,SAAQ,KAAK;IAIT,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM;IAHzD,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IAErC,8EAA8E;gBAClE,OAAO,EAAE,MAAM,EAAW,UAAU,CAAC,EAAE,MAAM,YAAA;CAG1D;AAED,uEAAuE;AACvE,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,gFAAgF;AAChF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAU;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAM3C;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAE7B,2EAA2E;AAC3E,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,SAAS,EAAG,WAAW,CAAU;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC,YAAY,CAAC,CAAC;IAC3D,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;gBAE/B,QAAQ,EAAE,uBAAuB;CAgB9C;AAED;;;wEAGwE;AACxE,qBAAa,0BAA2B,SAAQ,QAAQ;IACtD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAEnB,QAAQ,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM;CAMrE;AAED;2BAC2B;AAC3B,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;CAC5C"}
@@ -0,0 +1,7 @@
1
+ /** M-KOPA/launchpad-template commit the template-derived files come from. */
2
+ export declare const REACT_API_STARTER_TEMPLATE_COMMIT = "0c37b80a5fcb06f7c840ae26dd7be07d9ed62124";
3
+ /** Where each embedded file comes from. */
4
+ export declare const REACT_API_STARTER_PROVENANCE: Readonly<Record<string, string>>;
5
+ /** [relative path, file text] in write order. package.json and bun.lock first. */
6
+ export declare const REACT_API_STARTER_FILES: ReadonlyArray<readonly [string, string]>;
7
+ //# sourceMappingURL=react-api-starter-files.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"react-api-starter-files.d.ts","sourceRoot":"","sources":["../../src/scaffold/react-api-starter-files.ts"],"names":[],"mappings":"AAuBA,6EAA6E;AAC7E,eAAO,MAAM,iCAAiC,6CAA6C,CAAC;AAE5F,2CAA2C;AAC3C,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQzE,CAAC;AAibF,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ5E,CAAC"}
@@ -0,0 +1,26 @@
1
+ export { REACT_API_STARTER_FILES } from "./react-api-starter-files.js";
2
+ /** Build block for a manifest whose app is the starter (same as CWD detection gives it). */
3
+ export declare const REACT_API_STARTER_BUILD: {
4
+ readonly command: "bun install --frozen-lockfile && bun run build";
5
+ readonly destination_dir: "dist";
6
+ readonly root_dir: "";
7
+ };
8
+ /** Files that mean the folder already holds an app the starter must not mix into. */
9
+ export declare const EXISTING_APP_MARKERS: readonly string[];
10
+ export type StarterResult = {
11
+ readonly kind: "existing-app";
12
+ readonly marker: string;
13
+ } | {
14
+ readonly kind: "written";
15
+ readonly written: readonly string[];
16
+ readonly kept: readonly string[];
17
+ readonly skippedSymlink: readonly string[];
18
+ };
19
+ /** The first existing-app marker under `baseDir`, or undefined for a fresh folder. */
20
+ export declare function existingAppMarker(baseDir: string): string | undefined;
21
+ /**
22
+ * Write the starter under `baseDir`. `skip` names paths another scaffold owns
23
+ * (the secure template's router). Existing files are kept, never overwritten.
24
+ */
25
+ export declare function writeReactApiStarter(baseDir: string, skip?: ReadonlySet<string>): StarterResult;
26
+ //# sourceMappingURL=react-api-starter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"react-api-starter.d.ts","sourceRoot":"","sources":["../../src/scaffold/react-api-starter.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,4FAA4F;AAC5F,eAAO,MAAM,uBAAuB;;;;CAI1B,CAAC;AAEX,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAWjD,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C,CAAC;AAEN,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAErE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,WAAW,CAAC,MAAM,CAAa,GAAG,aAAa,CAsB1G"}
@@ -0,0 +1,57 @@
1
+ export declare const SECURE_API_LIB_PATH = "functions/_lib/secure-api.ts";
2
+ export declare const SECURE_API_ROUTER_PATH = "functions/api/[[path]].ts";
3
+ export declare const SECURE_API_TEST_PATH = "tests/secure-api.test.ts";
4
+ export declare const AUTHZ_ATTESTATION_PATH = "authz-attestation.json";
5
+ /** Paths the manifest's `app.include` needs so the scaffold ships with the app. */
6
+ export declare const SECURE_TEMPLATE_INCLUDE: readonly string[];
7
+ /** The statement the owner attests. Versioned so a later wording change is visible. */
8
+ export declare const AUTHZ_STATEMENT_ID = "launchpad-app-authz-v1";
9
+ export declare const AUTHZ_STATEMENT: string;
10
+ export declare const SECURE_API_LIB = "// Secure-by-default API helpers (scaffolded by `launchpad init --secure-template`).\n//\n// createSecureApi() registers the identity check FIRST, so every route added\n// to the returned app runs behind it. requireRole() is the role check for\n// routes that change data. tests/secure-api.test.ts fails if either is\n// bypassed. Do not create another Hono app under functions/.\n\nimport { Hono, type MiddlewareHandler } from \"hono\";\nimport { createJwksCache, parseGatewayAssertionFromHeaders } from \"@m-kopa/platform-auth\";\nimport { createPlatformAuthMiddleware, type PlatformAuthVariables } from \"@m-kopa/platform-auth/hono\";\n\n/**\n * Bindings the platform sets on a gateway-fronted app. Older Pages apps may\n * carry only the legacy names (CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD,\n * JWKS_URL), which hold the same gateway values; both sets are read.\n */\nexport interface SecureEnv {\n GATEWAY_ISSUER?: string;\n GATEWAY_AUD?: string;\n GATEWAY_JWKS_URL?: string;\n CF_ACCESS_TEAM_DOMAIN?: string;\n CF_ACCESS_AUD?: string;\n JWKS_URL?: string;\n [key: string]: unknown;\n}\n\ntype SecureVars<E extends SecureEnv> = { Bindings: E; Variables: PlatformAuthVariables };\nexport type SecureApp<E extends SecureEnv> = Hono<SecureVars<E>>;\n\nconst authGuards = new WeakSet<object>();\nconst roleGuards = new WeakSet<object>();\nconst passThroughs = new WeakSet<object>();\n\n/** True for the identity middleware created by createSecureApi (used by the tests). */\nexport function isAuthGuard(handler: unknown): boolean {\n return typeof handler === \"function\" && authGuards.has(handler);\n}\n\n/** True for a middleware created by requireRole (used by the tests). */\nexport function isRoleGuard(handler: unknown): boolean {\n return typeof handler === \"function\" && roleGuards.has(handler);\n}\n\n/** True for a middleware marked with passThrough (used by the tests). */\nexport function isPassThrough(handler: unknown): boolean {\n return typeof handler === \"function\" && passThroughs.has(handler);\n}\n\n/**\n * Mark a middleware that only observes the request and always calls next()\n * (logging, headers, timing) so app.use(...) does not need a role check. Never\n * wrap a handler that answers a request or changes data.\n */\nexport function passThrough<H extends MiddlewareHandler<any>>(handler: H): H {\n passThroughs.add(handler);\n return handler;\n}\n\nlet cachedJwks: ReturnType<typeof createJwksCache> | undefined;\nlet cachedJwksUrl: string | undefined;\nfunction jwksFor(url: string): ReturnType<typeof createJwksCache> {\n if (cachedJwks === undefined || cachedJwksUrl !== url) {\n cachedJwks = createJwksCache(url);\n cachedJwksUrl = url;\n }\n return cachedJwks;\n}\n\nfunction verifyIdentity<E extends SecureEnv>(): MiddlewareHandler<SecureVars<E>> {\n const guard: MiddlewareHandler<SecureVars<E>> = async (c, next) => {\n // No assertion: refuse before anything else runs.\n if (parseGatewayAssertionFromHeaders(c.req.raw.headers) === null) {\n return c.json({ error: \"unauthorized\" }, 401);\n }\n const issuer = c.env?.GATEWAY_ISSUER || c.env?.CF_ACCESS_TEAM_DOMAIN;\n const audience = c.env?.GATEWAY_AUD || c.env?.CF_ACCESS_AUD;\n if (!issuer || !audience) {\n // Fail closed: never serve a route when the verifier is not configured.\n return c.json({ error: \"identity_not_configured\" }, 503);\n }\n const jwksUrl =\n c.env?.GATEWAY_JWKS_URL || c.env?.JWKS_URL || `${issuer.replace(/\\/$/, \"\")}/.well-known/jwks.json`;\n // platform-auth types its middleware for its own Variables only; this app\n // also has Bindings, so the cast widens it to the app's context type.\n const middleware = createPlatformAuthMiddleware({\n header: \"gateway\",\n teamDomain: issuer,\n audience,\n jwks: jwksFor(jwksUrl),\n }) as unknown as MiddlewareHandler<SecureVars<E>>;\n return middleware(c, next);\n };\n authGuards.add(guard);\n return guard;\n}\n\n/** A Hono app under /api whose first handler verifies the caller's identity. */\nexport function createSecureApi<E extends SecureEnv>(): SecureApp<E> {\n const app = new Hono<SecureVars<E>>().basePath(\"/api\");\n app.use(\"*\", verifyIdentity<E>());\n return app;\n}\n\n/**\n * Allow the request only when the caller is in one of the Entra groups listed\n * (comma separated group object IDs) in ROLE_<ROLE>_GROUP_IDS. An unset or\n * empty list denies everyone: set it before the route can be used.\n *\n * The groups come from the verified gateway assertion, which is a login-time\n * snapshot: removing someone from a role group takes effect at their next\n * gateway sign-in, not at once. Use this for coarse roles (writer, admin).\n * When revocation must be immediate, look the role up server-side (your own\n * table or Microsoft Graph) instead.\n */\nexport function requireRole<E extends SecureEnv>(role: string): MiddlewareHandler<SecureVars<E>> {\n const key = `ROLE_${role.toUpperCase().replace(/[^A-Z0-9]/g, \"_\")}_GROUP_IDS`;\n const guard: MiddlewareHandler<SecureVars<E>> = async (c, next) => {\n const allowed = String(c.env?.[key] ?? \"\")\n .split(\",\")\n .map((g) => g.trim().toLowerCase())\n .filter((g) => g !== \"\");\n const user = c.get(\"user\");\n const groups = (user?.groups ?? []).map((g) => g.toLowerCase());\n if (allowed.length === 0 || !groups.some((g) => allowed.includes(g))) {\n return c.json({ error: \"forbidden\", role }, 403);\n }\n await next();\n return;\n };\n roleGuards.add(guard);\n return guard;\n}\n";
11
+ export declare const SECURE_API_ROUTER = "// API router (scaffolded by `launchpad init --secure-template`).\n//\n// Add every route to the app that buildApp() returns. Routes that change data\n// need requireRole(...) BEFORE the handler. tests/secure-api.test.ts checks\n// both. Keep the last line as it is: the guard test checks it.\n\nimport { handle } from \"hono/cloudflare-pages\";\nimport { createSecureApi, requireRole, type SecureEnv } from \"../_lib/secure-api\";\n\nexport interface Env extends SecureEnv {\n /** Comma separated Entra group object IDs allowed to write. */\n ROLE_WRITER_GROUP_IDS?: string;\n}\n\nexport function buildApp() {\n const app = createSecureApi<Env>();\n\n // Read route: any verified user of this app.\n app.get(\"/me\", (c) => {\n const user = c.get(\"user\");\n return c.json({ sub: user.sub, name: user.name ?? null });\n });\n\n // Write route: verified user AND in the writer role.\n app.post(\"/items\", requireRole<Env>(\"writer\"), async (c) => {\n return c.json({ ok: true }, 201);\n });\n\n return app;\n}\n\nexport const onRequest = handle(buildApp());\n";
12
+ export declare const SECURE_API_TEST = "// Guard test for the secure API template (audit A2-09). Do not delete.\n//\n// Fails when a route escapes the identity middleware, a route that can change\n// data has no role check in front of it, the router stops exporting the\n// secure app, or a route file appears outside the secure router.\n\nimport { lstatSync, readdirSync, readFileSync } from \"node:fs\";\nimport { join, relative } from \"node:path\";\nimport { describe, expect, test } from \"vitest\";\nimport { buildApp } from \"../functions/api/[[path]]\";\nimport { isAuthGuard, isPassThrough, isRoleGuard } from \"../functions/_lib/secure-api\";\n\n/** Methods that cannot change data. Everything else, ALL included, is a write. */\nconst READ_METHODS = new Set([\"GET\", \"HEAD\", \"OPTIONS\"]);\nconst ROUTER = \"functions/api/[[path]].ts\";\nconst LIB = \"functions/_lib/secure-api.ts\";\n\nconst ROUTE_EXPORT_RX = /export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+onRequest|export\\s*\\{[^}]*\\bonRequest/;\nconst NEW_HONO_RX = /new\\s+Hono\\b/g;\n\nfunction honoApps(text: string): number {\n return (text.match(NEW_HONO_RX) ?? []).length;\n}\n\nfunction samplePath(path: string): string {\n return path.replace(/:[^/]+/g, \"x\").replace(/\\*$/, \"x\");\n}\n\n/** True when a guard registered on `guardPath` runs for `path`. */\nfunction covers(guardPath: string, path: string): boolean {\n if (guardPath === path) return true;\n if (!guardPath.endsWith(\"/*\")) return false;\n const prefix = guardPath.slice(0, -1); // keeps the trailing \"/\"\n return path.startsWith(prefix) || path === prefix.slice(0, -1);\n}\n\n/** Files under dir. A symlink fails the test: it cannot be checked and can loop. */\nfunction walk(dir: string, root: string): string[] {\n let names: string[];\n try {\n names = readdirSync(dir);\n } catch {\n return [];\n }\n return names.flatMap((n) => {\n const p = join(dir, n);\n const st = lstatSync(p);\n expect(st.isSymbolicLink(), `${relative(root, p)} is a symlink; the guard test cannot check it`).toBe(false);\n return st.isDirectory() ? walk(p, root) : [p];\n });\n}\n\ndescribe(\"secure API template\", () => {\n const app = buildApp();\n const routes = app.routes;\n\n test(\"the identity middleware is the first handler and covers every route\", () => {\n expect(isAuthGuard(routes[0]?.handler)).toBe(true);\n expect(routes[0]?.path).toBe(\"/api/*\");\n expect(routes.filter((r) => isAuthGuard(r.handler))).toHaveLength(1);\n });\n\n test(\"every route refuses a request without an identity assertion\", async () => {\n for (const r of routes) {\n if (isAuthGuard(r.handler)) continue;\n const method = r.method === \"ALL\" ? \"GET\" : r.method;\n const res = await app.request(samplePath(r.path), { method });\n expect(res.status, `${method} ${r.path}`).toBe(401);\n }\n });\n\n test(\"every route that can change data has requireRole(...) in front of it\", () => {\n routes.forEach((w, i) => {\n if (READ_METHODS.has(w.method)) return;\n if (isAuthGuard(w.handler) || isRoleGuard(w.handler) || isPassThrough(w.handler)) return;\n // A role guard must run first: registered earlier, for the same method\n // (or every method), on a path that covers this one. An ALL route needs\n // an ALL guard, since a POST-only guard leaves DELETE open.\n const guarded = routes.slice(0, i).some(\n (g) =>\n isRoleGuard(g.handler) &&\n (g.method === \"ALL\" || (w.method !== \"ALL\" && g.method === w.method)) &&\n covers(g.path, w.path),\n );\n expect(guarded, `${w.method} ${w.path} has no requireRole(...) before its handler (wrap an observe-only middleware in passThrough(...))`).toBe(true);\n });\n });\n\n test(\"the router exports the secure app and nothing else\", () => {\n const text = readFileSync(join(process.cwd(), ROUTER), \"utf8\");\n expect(text, `${ROUTER} must end with: export const onRequest = handle(buildApp());`).toMatch(\n /^export const onRequest = handle\\(buildApp\\(\\)\\);$/m,\n );\n expect(text.match(/export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+onRequest\\w*/g), ROUTER).toHaveLength(1);\n expect(/export\\s*\\{[^}]*\\bonRequest|export\\s+default\\b/.test(text), `${ROUTER} has another export`).toBe(false);\n expect(honoApps(text), `${ROUTER} creates its own Hono app`).toBe(0);\n const lib = readFileSync(join(process.cwd(), LIB), \"utf8\");\n expect(honoApps(lib), `${LIB} creates one Hono app (createSecureApi)`).toBe(1);\n expect(ROUTE_EXPORT_RX.test(lib), `${LIB} exports a route handler`).toBe(false);\n });\n\n test(\"no route handlers outside the secure router\", () => {\n const root = process.cwd(); // vitest runs from the app root\n for (const abs of walk(join(root, \"functions\"), root)) {\n const rel = relative(root, abs).split(\"\\\\\").join(\"/\");\n if (rel === ROUTER || rel === LIB || !/\\.(m?[jt]sx?)$/.test(rel)) continue;\n const text = readFileSync(abs, \"utf8\");\n expect(ROUTE_EXPORT_RX.test(text), `${rel} exports a route handler`).toBe(false);\n expect(honoApps(text), `${rel} creates its own Hono app`).toBe(0);\n }\n });\n});\n";
13
+ /** Attestation record states. Only `attested` means the owner attested. */
14
+ export type AttestationStatus = "attested" | "attested_by_other" | "pending";
15
+ /** The signed-in identity that attested, as the bot verified it (`/me/identity`). */
16
+ export interface Attester {
17
+ readonly oid: string;
18
+ readonly email: string;
19
+ }
20
+ export interface AttestationInput {
21
+ /** Manifest owner. Only the owner's attestation counts. */
22
+ readonly owner: string;
23
+ /** ISO date (YYYY-MM-DD). */
24
+ readonly date: string;
25
+ /**
26
+ * Who attested, from the signed-in session. Omitted when nobody attested
27
+ * or the identity could not be verified: the record is then `pending`.
28
+ */
29
+ readonly attester?: Attester;
30
+ }
31
+ /** `attested` only when the verified attester is the manifest owner. */
32
+ export declare function attestationStatus(input: AttestationInput): AttestationStatus;
33
+ /**
34
+ * The attestation record committed with the app. The attester is bound to
35
+ * the signed-in Launchpad identity, not to a flag. It is still a local file:
36
+ * `server_recorded: false` until the bot captures attestations server-side.
37
+ */
38
+ export declare function attestationJson(input: AttestationInput): string;
39
+ export interface ScaffoldResult {
40
+ readonly written: readonly string[];
41
+ readonly kept: readonly string[];
42
+ /** Not written because a symlink sits on the path (it could point outside the app). */
43
+ readonly skippedSymlink: readonly string[];
44
+ }
45
+ /** True when `rel` under `baseDir`, or a folder on the way, is a symlink. */
46
+ export declare function symlinkOnPath(baseDir: string, rel: string): boolean;
47
+ /**
48
+ * Write the scaffold under `baseDir`. Existing files are kept, never
49
+ * overwritten, and nothing is written through a symlink.
50
+ */
51
+ export declare function writeSecureApiScaffold(baseDir: string, attestation: AttestationInput): ScaffoldResult;
52
+ /**
53
+ * Replace `authz-attestation.json` (the attest-later path). Refuses a symlink.
54
+ * Returns false when the file cannot be written safely.
55
+ */
56
+ export declare function writeAttestation(baseDir: string, attestation: AttestationInput): boolean;
57
+ //# sourceMappingURL=secure-api-template.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"secure-api-template.d.ts","sourceRoot":"","sources":["../../src/scaffold/secure-api-template.ts"],"names":[],"mappings":"AA6BA,eAAO,MAAM,mBAAmB,iCAAiC,CAAC;AAClE,eAAO,MAAM,sBAAsB,8BAA8B,CAAC;AAClE,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAC/D,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAAyC,CAAC;AAE/F,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAC3D,eAAO,MAAM,eAAe,QAGoC,CAAC;AAEjE,eAAO,MAAM,cAAc,69KAoI1B,CAAC;AAEF,eAAO,MAAM,iBAAiB,8jCAgC7B,CAAC;AAEF,eAAO,MAAM,eAAe,+mKAgH3B,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,mBAAmB,GAAG,SAAS,CAAC;AAE7E,qFAAqF;AACrF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAMD,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAG5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAmB/D;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,uFAAuF;IACvF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAanE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,GAAG,cAAc,CAyBrG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAIxF"}
package/dist/version.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const CLI_VERSION = "0.76.0";
1
+ export declare const CLI_VERSION = "0.78.0";
2
2
  //# sourceMappingURL=version.d.ts.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@m-kopa/launchpad-cli",
3
- "version": "0.76.0",
3
+ "version": "0.78.0",
4
4
  "description": "Launchpad CLI — clone / deploy / review / merge against Launchpad-managed apps. Talks to the portal-bot endpoints (SCOPE-M-760 / T4).",
5
5
  "type": "module",
6
6
  "bin": {
@@ -33,7 +33,7 @@
33
33
  "dependencies": {
34
34
  "esbuild": "0.28.1",
35
35
  "yaml": "2.9.0",
36
- "zod": "4.4.3"
36
+ "zod": "4.6.6"
37
37
  },
38
38
  "devDependencies": {
39
39
  "@types/node": "22.18.10",
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-content-pr
3
3
  description: Push a content change to a Launchpad app via `launchpad deploy` and verify it shipped via `launchpad status`. Covers the post-first-deploy iteration loop (edit → deploy → verify) - subsequent deploys commit directly to the app repo's main, then the dispatch delivery (or, for a legacy Pages app, the Pages build) runs asynchronously, so verification is its own step. Use when someone says "push a content change", "ship an update", "/launchpad-content-pr", "verify my deploy", or after `/launchpad-deploy` reports `done` and they want to follow up with an edit.
4
- version: 0.76.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -118,7 +118,38 @@ iteration loop is not the right tool — route to
118
118
  (teardown) instead. If it shows `failed` but the app is actually
119
119
  serving (e.g. a verification timed out after the real deploy
120
120
  succeeded), `launchpad recover <slug>` reconciles the record against
121
- live Cloudflare state.
121
+ live Cloudflare state. `recover` checks the app's Pages project, so it is a
122
+ Pages-app verb (a container app has its own path): on a dispatch app it
123
+ answers `not_live` and changes nothing. For a dispatch app that failed, see
124
+ `/launchpad-deploy-status`.
125
+
126
+ ## Second deploy from the folder `launchpad init` made: "no trusted source baseline"
127
+
128
+ The folder where the user ran `launchpad init` and the first `launchpad deploy`
129
+ is not a clone. The first deploy works from it; the next one stops with:
130
+
131
+ ```text
132
+ this working tree has no trusted source baseline
133
+ ```
134
+
135
+ The CLI suggests `launchpad pull --bootstrap`, a fresh clone, or
136
+ `--allow-unguarded`. Only the fresh clone works. `launchpad pull` answers
137
+ "missing source provenance", and `pull --bootstrap` is only for a legacy clone
138
+ with a clean synthetic baseline. Do not use `--allow-unguarded` here: it turns
139
+ off the protection against overwriting newer edits and is meant for an
140
+ intentional non-clone tree. Do this instead, in a new empty folder next to the
141
+ old one:
142
+
143
+ ```bash
144
+ mkdir ../my-app-clone && cd ../my-app-clone
145
+ launchpad clone <slug>
146
+ cd launchpad-app-<slug>
147
+ ```
148
+
149
+ Copy the edited files from the old folder into `launchpad-app-<slug>/`, then run
150
+ `launchpad deploy` from there. A clone also holds the starter files the
151
+ platform added (for example `.github/`, `AGENTS.md`); leave them in place. From
152
+ now on deploy only from the clone.
122
153
 
123
154
  ## Edit and ship
124
155
 
@@ -259,7 +290,7 @@ group passes (no need to use `deploy --dry-run` as a workaround).
259
290
  > No second deploy is required.
260
291
  > The CLI must not report access success before the apply reaches `applied`.
261
292
  > A local timeout exits non-zero while durable server recovery remains active.
262
- > Preview with `--dry-run` and undo a bad change with `launchpad rollback <prior-sha>`.
293
+ > Preview with `--dry-run`. To undo a bad change, put the previous `launchpad.yaml` back and run `launchpad deploy`; `launchpad rollback` is not the way (see the verb list below).
263
294
  > Do not tell the user to raise a request with the platform team.
264
295
  > See
265
296
  > `/launchpad-status` and the
@@ -355,8 +386,14 @@ Once you've shipped first content, the daily-use verbs are:
355
386
  no-op that prints `no redeploy needed` and exits 0; it does not
356
387
  re-run the dispatch build. To rebuild a dispatch app, ship a change
357
388
  with `launchpad deploy`.
358
- - **`launchpad envvars`** — list / set / remove non-secret
359
- production env vars.
389
+ - **`launchpad envvars`** - Pages apps only: list / set / remove
390
+ production env vars on the app's Pages project. On an app whose
391
+ settings live in the manifest (every new dispatch app) `set` and `rm`
392
+ change nothing and print the supported route: declare the variable
393
+ under `spec.env_vars` in `launchpad.yaml` and run `launchpad deploy`
394
+ (see `/launchpad-deploy`). On the 16 Nov test `envvars list` on a
395
+ dispatch app answered 502 `env_vars_read_failed` ("project ... not found
396
+ yet"): that is the missing Pages project, not a fault in the app.
360
397
  - **`launchpad secrets template`** — emit `.env.example` from the
361
398
  manifest's secret bindings.
362
399
  - **`launchpad secrets push`** - push secret values from `.env`
@@ -382,8 +419,12 @@ Once you've shipped first content, the daily-use verbs are:
382
419
  app has no Pages deployment history, so `logs` just says so and
383
420
  points at `launchpad status`, which shows the delivery stage, any
384
421
  refusal reason and, when there is one, the GitHub Actions run URL.
385
- - **`launchpad rollback`** — revert manifest to a prior git SHA +
386
- re-apply.
422
+ - **`launchpad rollback`** - reverts the **manifest only** (not content) to
423
+ a prior git SHA and re-applies it. The historical manifest must parse
424
+ against the v1alpha1 schema, so it fails on an app with a v2 manifest
425
+ (every new dispatch app). To undo a content change on any app: in the
426
+ clone, restore the old file's contents in the clone (from the user's own
427
+ copy of the previous version), then run `launchpad deploy`. That ships the old content as a new commit.
387
428
 
388
429
  ## Don'ts
389
430
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-deploy
3
3
  description: Walk a Launchpad user through deploying an app from their local working directory (Model A — `launchpad init` + `launchpad deploy`). Wraps the CLI verbs end-to-end: detects the app shape, scaffolds `launchpad.yaml`, resolves the allowed Entra group via `launchpad groups`, bundles the CWD via `launchpad deploy`, and watches the rollout via `launchpad status`. Use when someone says "deploy a new app", "ship my app to Launchpad", "/launchpad-deploy", "I have an app locally — get it on Launchpad", or any variant. Resume/abandon for legacy in-flight provisioning is at the bottom.
4
- version: 0.76.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -71,6 +71,15 @@ Catalogue listing controls discovery only.
71
71
  It neither grants access nor makes an app private.
72
72
  Platform-admin entry is independent of app groups, ownership and listing, and does not assign app-specific business roles.
73
73
 
74
+ ## Access agreement
75
+
76
+ Every person who deploys must accept the Launchpad access agreement once a year.
77
+ If a command stops with exit code `43` or `agreement_required`, or `launchpad login` says the agreement needs accepting, stop.
78
+ Tell the human to read it (`launchpad agreement show`) and to run `launchpad agreement accept` themselves in their own terminal.
79
+ Never type the acceptance phrase, never pipe input into `accept`, and never claim the human accepted.
80
+ An AI agent may not accept the agreement for a person.
81
+ `launchpad destroy` is never blocked by the agreement.
82
+
74
83
  ## Constants (single source of truth)
75
84
 
76
85
  These values are referenced by `/launchpad-deploy-status`,
@@ -236,6 +245,19 @@ against an existing file is rejected unless `--force` is passed —
236
245
  the manifest is the user's authored artefact, the CLI does not
237
246
  silently overwrite it.
238
247
 
248
+ **What `init` does not create.** `launchpad init` writes `./launchpad.yaml`
249
+ and adds `.env` / `.env.local` to `.gitignore`. For a `static` app it also
250
+ writes a starter `static/index.html` when none exists. For `react` it writes
251
+ no app code: the project (`package.json`, lockfile, `src/`) is the user's own,
252
+ and `launchpad deploy` ships what is already in the folder. If the folder is
253
+ empty, tell the user to add their app first. For `react+api`, CLI 0.78.0 and
254
+ newer also writes a working starter app (§A.2b) unless `--no-starter` is
255
+ passed; it writes nothing when the folder already has a `package.json`, a
256
+ lockfile or a `vite.config.*`, and never overwrites a file. Check
257
+ `launchpad --version` before relying on it. (`--secure-template`, which
258
+ scaffolds a secure `react+api` router, needs CLI 0.77.0 or newer; with the
259
+ starter, the secure router replaces the starter router.)
260
+
239
261
  **Stack constraints by app-type** (single source of truth:
240
262
  `launchpad-platform/ARCHITECTURE.md § Tech Stack` and `PATTERNS.md §
241
263
  Approved Libraries`). Surface this table to the user **before** they
@@ -260,6 +282,85 @@ the existing app uses any of these, plan the swap **before** picking
260
282
  a slug — do not deploy first and port later. What the bot *does*
261
283
  enforce at deploy time is the gate set in §A.5.
262
284
 
285
+ ### A.2b React API app: the short path
286
+
287
+ A `react+api` app on dispatch went live from one `launchpad deploy` in 477 s
288
+ (observed on 16-17 Nov 2026) when it started from the platform's files. Two
289
+ earlier runs that used their own `package.json` and their own
290
+ `functions/api/*.js`, or a newer bun, failed the first delivery build. CLI
291
+ 0.78.0 and newer writes those files for you, so the path is short.
292
+
293
+ **Why the app must start from the platform's files.** The bootstrap pull
294
+ request seeds a `react+api` app with a `functions/api/[[path]].ts` Hono router
295
+ that imports `hono` and `@m-kopa/platform-auth`. The first delivery build
296
+ compiles it, so if the owner's `package.json` lacks those two dependencies the
297
+ build fails with `Could not resolve "hono/cloudflare-pages"` and the app ends
298
+ `provisioning_failed` at `deployment_verified`.
299
+
300
+ 1. **Run `launchpad init --type react+api`** (with the other init flags from
301
+ §A.2) in an empty folder. It writes the manifest and a working starter:
302
+ `package.json` (with `hono`, `@m-kopa/platform-auth`, React, Vite and a
303
+ `build` script), a `bun.lock` written by bun 1.3.4, `tsconfig.json`, the
304
+ router `functions/api/[[path]].ts`, a page (`index.html`, `src/main.jsx`) and
305
+ `vite.config.js`; the manifest gets `spec.build`. `--no-starter` writes only
306
+ the manifest. Check `launchpad --version` shows 0.78.0 or newer first; an
307
+ older CLI writes no starter.
308
+ 2. **Add API routes inside the starter's router**, in
309
+ `functions/api/[[path]].ts`. Never add a second functions file such as
310
+ `functions/api/hello.js` beside it: it is a competing route. Add the app's
311
+ own packages with `npx --yes bun@1.3.4 add <package>` so the lockfile stays
312
+ at version 1.
313
+ 3. **Run the local gate** with bun 1.3.4, in the app folder. The last command is
314
+ the functions compile that the delivery workflow runs:
315
+
316
+ ```bash
317
+ npx --yes bun@1.3.4 install --frozen-lockfile --ignore-scripts
318
+ npx --yes bun@1.3.4 x tsc --noEmit
319
+ npx --yes bun@1.3.4 run test
320
+ npx --yes bun@1.3.4 run build
321
+ npx --yes wrangler@4.136.3 pages functions build functions --outdir "$(mktemp -d)" --compatibility-date 2026-07-27 --compatibility-flags nodejs_compat
322
+ ```
323
+
324
+ Every command must exit 0. The functions compile catches a missing `hono` or
325
+ `@m-kopa/platform-auth`; `launchpad validate` and `launchpad deploy
326
+ --dry-run` do not.
327
+ 4. **`launchpad validate`, then ONE `launchpad deploy`.** The first deploy
328
+ ships the content; do not deploy again to check.
329
+
330
+ **When `init` writes no starter.** `init` writes nothing beyond the manifest
331
+ when the folder already has a `package.json`, a lockfile or a `vite.config.*`,
332
+ and it never overwrites a file; it says why. For such an existing app, bring it
333
+ in line by hand: keep `hono` and `@m-kopa/platform-auth` in `package.json`
334
+ (the platform's reference files are `react-api/starter/` and
335
+ `react-api/functions/api/[[path]].ts` in `M-KOPA/launchpad-template`), put the
336
+ routes in the one `functions/api/[[path]].ts` router, give `package.json` a
337
+ `build` script such as `"build": "vite build"`, make sure the manifest has
338
+ `spec.build` (`bun install --frozen-lockfile && bun run build`, destination
339
+ `dist`), install with `npx --yes bun@1.3.4 install`, then run steps 3 and 4.
340
+
341
+ Two traps (observed on 16-17 Nov 2026):
342
+
343
+ - **Hidden files in the build output.** The build output (`dist`) must contain
344
+ no hidden files or folders: do not create `public/.gitkeep`, because Vite
345
+ copies it into `dist` and dispatch refuses the delivery.
346
+ - **A global `~/.npmrc` that routes `@m-kopa` to another registry** (for
347
+ example GitHub Packages) can make the install 404 for
348
+ `@m-kopa/platform-auth`, which is on the public npm registry. Put one line
349
+ in a project `.npmrc`: `@m-kopa:registry=https://registry.npmjs.org`. Never
350
+ put a token in it; the bot rejects a bundle whose `.npmrc` carries auth.
351
+
352
+ **bun version.** The template workflows build with bun 1.3.4
353
+ (`bun-version: "1.3.4"`). A lockfile written by bun 1.4 or newer has
354
+ `"lockfileVersion": 2`, which bun 1.3.4 cannot read: the first delivery build
355
+ fails at "Install dependencies" with `Unknown lockfile version`, and the app
356
+ ends `provisioning_failed` at `deployment_verified`. `launchpad deploy` now
357
+ checks this itself before it uploads anything (see §A.5, "Pre-flight checks").
358
+ If it reports a lockfile problem, the fix is:
359
+
360
+ ```bash
361
+ npx --yes bun@1.3.4 install
362
+ ```
363
+
263
364
  ### A.3 Deliberately share with an Entra group
264
365
 
265
366
  The CLI resolves Entra groups via the bot's `/groups` endpoint
@@ -299,7 +400,9 @@ Never use the assigned `groups list` shortlist as identity or drift authority.
299
400
  --strict-groups`, `launchpad groups resolve <name|uuid>`, and
300
401
  `launchpad deploy --dry-run` all resolve against the **whole tenant**
301
402
  (PS-1859), so any of them correctly accepts a valid unassigned group.
302
- Use whichever fits; `--dry-run` additionally previews the Terraform.
403
+ Use whichever fits; `--dry-run` additionally previews the Terraform, but it
404
+ needs a git repository with at least one commit (a fresh `launchpad init`
405
+ folder has none).
303
406
 
304
407
  This `--group` flow sets the group at first deploy.
305
408
  Changing groups on an existing app still uses a plain `launchpad deploy`.
@@ -336,8 +439,8 @@ they want to confirm they'll still be able to reach it.
336
439
  launchpad validate
337
440
  ```
338
441
 
339
- Parses `launchpad.yaml` against the v1alpha1 schema and reports
340
- problems. Doesn't talk to the bot by default. Useful when the user
442
+ Parses `launchpad.yaml` and reports problems (it accepts both the v1alpha1
443
+ and the v2 manifest). Doesn't talk to the bot by default. Useful when the user
341
444
  wants a second look before paying for an upload round-trip.
342
445
 
343
446
  Add `--strict-groups` to *additionally* resolve the manifest's
@@ -349,12 +452,46 @@ network (exit 1 = group not found / ineligible / ambiguous,
349
452
  2 = network error, 3 = no valid session **or the caller is not an
350
453
  employee** — the tenant resolve is employee-gated).
351
454
 
455
+ `launchpad plan` and `launchpad generate` read only the v1alpha1 manifest.
456
+ The v2 manifest that `launchpad init` writes (`apiVersion: launchpad.m-kopa.us/v2`,
457
+ a `spec:` block) makes both fail with `Unrecognized key: spec`, although the
458
+ manifest is fine. For a v2 manifest use `launchpad validate`, and
459
+ `launchpad deploy --dry-run` to preview (it needs a git repository with at
460
+ least one commit: run `git init` and commit first, or it fails with "failed to
461
+ resolve git HEAD"). Do not "fix" the manifest to satisfy
462
+ `plan`, and do not rewrite it as v1.
463
+
464
+ **Declaring env vars and secrets (v2 / dispatch app).** Add them to the
465
+ manifest under `spec.env_vars`; the key must be `UPPER_SNAKE_CASE`, and each
466
+ entry is either a plain value or a secret reference:
467
+
468
+ ```yaml
469
+ spec:
470
+ env_vars:
471
+ GREETING:
472
+ type: plain_text
473
+ value: hello
474
+ DEMO_TOKEN:
475
+ type: secret_text
476
+ secret_ref: demo-token
477
+ ```
478
+
479
+ A name ending `_TOKEN` or `_SECRET` must be `secret_text`. Put the secret's
480
+ value in `.env` as `DEMO_TOKEN=<value>`, deploy, and once `launchpad status`
481
+ shows the first delivery push it (the value goes to the dispatch Worker and is
482
+ live at once, with no redeploy), then check that it is set:
483
+
352
484
  ```bash
353
- launchpad plan
485
+ launchpad secrets push --yes
486
+ launchpad secrets status
354
487
  ```
355
488
 
356
- Same, but also summarises what the manifest would deploy: hostnames,
357
- build command, destination directory, allowed group. Still offline.
489
+ If the values are in a file other than `.env`, use `launchpad secrets push
490
+ --env <file> --yes` (`--env` is a documented flag; observed on 17 Nov 2026,
491
+ `--help` is not supported). `secrets status` lists names only
492
+ (PRESENT/MISSING). The manifest never holds the value. `launchpad envvars set` is for Pages apps only: on an app
493
+ managed through the manifest it changes nothing and prints this route.
494
+ `launchpad secrets template` writes `.env.example` from the declared names.
358
495
 
359
496
  ### A.5 Deploy
360
497
 
@@ -368,7 +505,31 @@ plus a built-in default-ignore set — it never shells out to
368
505
  gzips it, and POSTs to the bot's `/apps/<slug>/deploy/bundle`
369
506
  endpoint. Files outside the manifest's app boundary (`app.root` /
370
507
  `app.include`) and never-shippable files (private keys, `.env`
371
- material) are stripped with a warning before upload.
508
+ material) are stripped with a warning before upload. The default
509
+ `app.include` that `launchpad init` writes covers the lockfiles, `package.json`,
510
+ `tsconfig*.json`, `vite.config.*`, `src/**` and `public/**` (plus `functions/**`
511
+ for `react+api`); it leaves out lint config (`eslint.config.*`) and tests
512
+ (`test/**`, `vitest.config.*`). Add them to `spec.app.include` when the app's
513
+ CI needs them.
514
+
515
+ **Pre-flight checks (CLI 0.78.0 and newer).** Before it uploads anything,
516
+ `launchpad deploy` looks at the bundle for two shapes that fail the delivery
517
+ build. It refuses (exit 1, nothing uploaded) only when the build is certain to
518
+ fail, and prints a warning, then continues, in every other case:
519
+
520
+ - a `bun.lock` with `"lockfileVersion"` 2 or newer, which the build's bun 1.3.4
521
+ cannot read. It is refused only for a dispatch app whose build runs
522
+ `bun install --frozen-lockfile` on that lockfile; elsewhere it warns. Fix:
523
+ `npx --yes bun@1.3.4 install`.
524
+ - a dispatch `react+api` app that ships no API router of its own and whose
525
+ `package.json` is missing, is not valid JSON, or lacks `hono` or
526
+ `@m-kopa/platform-auth` (the seeded router imports both). A package missing
527
+ for a router the app does ship only warns. Fix: `npx --yes bun@1.3.4 add hono
528
+ @m-kopa/platform-auth`, or the install command above.
529
+
530
+ Each refusal names the flag `--allow-preflight-failure`, which turns refusals
531
+ into warnings. Do not pass it to get past a refusal: fix the named file first.
532
+ It is valid only for a content deploy.
372
533
 
373
534
  ### Container apps — use `auth: gateway` (AIO-811)
374
535
 
@@ -435,6 +596,55 @@ fresh slug auto-provisions:
435
596
  Confirm the deployed commit and successful build with `launchpad status <slug>`.
436
597
  A merged commit alone does not prove delivery on either origin.
437
598
 
599
+ **First deploy: what to expect and what to check.**
600
+
601
+ - **Time.** Expect 5-10 minutes from the bot accepting the deploy to `live`
602
+ (three runs on 16-17 Nov 2026 took about 8 to 9.5 minutes). The CLI waits
603
+ about 8 minutes, and returns earlier if the deploy fails inside that window.
604
+ - **Exit 0 after `Still provisioning (stage: ...)` is not success.** The wait
605
+ expired and the app is not live yet; the CLI still exits 0, and its last line
606
+ now reads `Deploy NOT finished: <slug> is still provisioning and is not live
607
+ yet`. Never tell the user it is deployed. Run:
608
+
609
+ ```bash
610
+ launchpad watch <slug>
611
+ ```
612
+
613
+ and, for a one-shot read, `launchpad status <slug>`. Only `live` (and for
614
+ dispatch, `v2 delivery: state delivered`) is done.
615
+ - **HTTP 503 `gateway_capacity_unavailable`** ("Gateway capacity could not be
616
+ verified. No app was created.") on a first deploy: nothing was created, so
617
+ nothing needs cleaning up. Wait 30 seconds and run the same `launchpad
618
+ deploy` again. Each attempt itself takes about 30 seconds. After 7 failed
619
+ attempts stop and run `/launchpad-report` with the slug and the error text;
620
+ never switch to another slug. A fix for this fault is in review.
621
+ `503 enforced_access_unavailable` ("cannot verify enforced access from
622
+ Terraform - retry shortly") is a retryable 503 too: same wait, same limit.
623
+ Do not change the manifest, the groups or the slug to get past it.
624
+ - **A failed bootstrap check is a platform fault, not your lockfile.**
625
+ The bot's bootstrap pull request runs CI (the `launchpad-review` workflow) on
626
+ the platform's starter files, not on your app. If it fails (for example
627
+ `bootstrap PR #1 CI failed: failed checks: npm-audit`), the first deploy ends
628
+ `bot_pr_ci_failed`. The starter's advisories and the audit script are fixed
629
+ for new apps, so this should not happen; if it does, report it with
630
+ `/launchpad-report`. Do not change your lockfile and do not retry under
631
+ another slug. `launchpad status` may still suggest running `bun audit
632
+ --prod`; that does not predict this check. To clear the slug, the owner runs
633
+ `launchpad destroy <slug> --confirm-slug <slug> --yes` (see
634
+ `/launchpad-deploy-status`).
635
+
636
+ What the bootstrap CI runs on the first PR, on the starter files (jobs `lint`,
637
+ `typecheck`, `test`, `gitleaks`, `npm-audit`):
638
+ - install with `bun install --frozen-lockfile`, so a committed `bun.lock`
639
+ that matches `package.json` is required;
640
+ - lint (`eslint .`), so the app needs an ESLint config;
641
+ - typecheck (`tsc --noEmit`) and test (`bun run test`), so the app needs a
642
+ `tsconfig.json` and a `test` script in `package.json`;
643
+ - the secret scan (`gitleaks`) and `bun audit`.
644
+
645
+ Your own files are built later, by the first delivery build (`launchpad-build`),
646
+ which installs with bun 1.3.4 and compiles `functions/`; see §A.2b.
647
+
438
648
  **What the bot enforces at deploy time** (the real gate set — there
439
649
  is no dependency/stack-fit gate, see §A.2):
440
650
 
@@ -488,6 +698,10 @@ Flags — there is nothing useful to pass on the Model A path:
488
698
  Run `/launchpad-status` to confirm; `/launchpad-content-pr` is no
489
699
  longer needed under Model A (the first deploy already shipped your
490
700
  content)."
701
+ - **`couldn't reach the served URL to verify: served URL redirected (HTTP 302)`**
702
+ after a successful deploy is expected for an app behind gateway sign-in: the
703
+ CLI has no browser session, so the app sends it to sign-in. It is not a
704
+ failure. Confirm with `launchpad status <slug>`.
491
705
  - **Terminal failure stages** — `validator_rejected`,
492
706
  `tf_apply_failed`, `bot_pr_ci_failed`, `abandoned`, `failed` → run
493
707
  `/launchpad-deploy-status <slug>` and surface the failure reason
@@ -496,6 +710,22 @@ Flags — there is nothing useful to pass on the Model A path:
496
710
  symlinks, secret-pattern hits, build-command violations) are
497
711
  rejected at upload and self-describing in the CLI's stderr; surface
498
712
  them verbatim and let the user fix and re-`launchpad deploy`.
713
+ - **First deploy ended `provisioning_failed` / `bot_pr_ci_failed`** (for
714
+ example `bootstrap PR #1 CI failed: failed checks: npm-audit`) → a platform
715
+ fault. The owner can now free the slug: `launchpad destroy <slug>
716
+ --confirm-slug <slug> --yes` releases it in seconds (proven on production on
717
+ 17 Nov 2026). Do not create a second slug before that destroy, and do not
718
+ loop `deploy`, `recover`, `--resume`, `--abandon` or `--allow-unguarded`:
719
+ none of them clears it. Follow `/launchpad-deploy-status` § "First deploy
720
+ stuck at `provisioning_failed`", and run `/launchpad-report` with the slug
721
+ if the destroy is refused.
722
+ - **First deploy ended `provisioning_failed` at `deployment_verified`** with
723
+ `dispatch delivery refused: build-failed` (the bootstrap PR merged, the first
724
+ delivery build failed) → follow `/launchpad-deploy-status` § "First deploy
725
+ failed at `deployment_verified`". Do not use `launchpad recover`: it does not
726
+ apply to dispatch apps. From CLI 0.78.0, `launchpad status` no longer
727
+ suggests it for a dispatch app; it says to fix the cause, destroy and deploy
728
+ again. An older CLI may still print the `recover` line: ignore it.
499
729
  - **Dispatch delivery refused** (`launchpad status` shows `v2 delivery:
500
730
  state refused`) → surface the `failed at` reason verbatim. For
501
731
  `hidden build output is not supported`, follow the fix in §A.2 and
@@ -507,8 +737,8 @@ Flags — there is nothing useful to pass on the Model A path:
507
737
  was moved from dispatch to Pages needs the platform team to return
508
738
  it to dispatch (`launchpad migrate` only moves live Pages apps), so
509
739
  offer `/launchpad-report` with the slug and the error.
510
- - **Terminal-failed but the app is actually serving** → `launchpad
511
- recover <slug>`. The bot re-derives reality from live Cloudflare
740
+ - **Terminal-failed but the app is actually serving** (a Pages app; `recover`
741
+ refuses dispatch apps) → `launchpad recover <slug>`. The bot re-derives reality from live Cloudflare
512
742
  state and repairs the record to `live` only when the app is
513
743
  verifiably serving; if it isn't, it refuses with exactly what was
514
744
  checked — it never fabricates a live state.