@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.
- package/CHANGELOG.md +35 -0
- package/dist/bundle/upload.d.ts +16 -0
- package/dist/bundle/upload.d.ts.map +1 -1
- package/dist/cli.js +3415 -597
- package/dist/commands/admin-cli-sessions.d.ts +6 -0
- package/dist/commands/admin-cli-sessions.d.ts.map +1 -0
- package/dist/commands/admin.d.ts.map +1 -1
- package/dist/commands/agreement.d.ts +44 -0
- package/dist/commands/agreement.d.ts.map +1 -0
- package/dist/commands/app-lints.d.ts +14 -0
- package/dist/commands/app-lints.d.ts.map +1 -0
- package/dist/commands/deploy-flags.d.ts +2 -0
- package/dist/commands/deploy-flags.d.ts.map +1 -1
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/destroy.d.ts +36 -0
- package/dist/commands/destroy.d.ts.map +1 -1
- package/dist/commands/disable.d.ts +42 -0
- package/dist/commands/disable.d.ts.map +1 -0
- package/dist/commands/init.d.ts +10 -0
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/login.d.ts +4 -1
- package/dist/commands/login.d.ts.map +1 -1
- package/dist/commands/status.d.ts +13 -1
- package/dist/commands/status.d.ts.map +1 -1
- package/dist/commands/validate.d.ts.map +1 -1
- package/dist/deploy/preflight.d.ts +134 -0
- package/dist/deploy/preflight.d.ts.map +1 -0
- package/dist/deploy/verify-deploy.d.ts.map +1 -1
- package/dist/destroy-failure.d.ts +23 -0
- package/dist/destroy-failure.d.ts.map +1 -0
- package/dist/dispatcher.d.ts.map +1 -1
- package/dist/http/api-client.d.ts +16 -2
- package/dist/http/api-client.d.ts.map +1 -1
- package/dist/http/error-envelope.d.ts +13 -1
- package/dist/http/error-envelope.d.ts.map +1 -1
- package/dist/http/errors.d.ts +18 -0
- package/dist/http/errors.d.ts.map +1 -1
- package/dist/scaffold/react-api-starter-files.d.ts +7 -0
- package/dist/scaffold/react-api-starter-files.d.ts.map +1 -0
- package/dist/scaffold/react-api-starter.d.ts +26 -0
- package/dist/scaffold/react-api-starter.d.ts.map +1 -0
- package/dist/scaffold/secure-api-template.d.ts +57 -0
- package/dist/scaffold/secure-api-template.d.ts.map +1 -0
- package/dist/version.d.ts +1 -1
- package/package.json +2 -2
- package/skills/launchpad-content-pr/SKILL.md +48 -7
- package/skills/launchpad-deploy/SKILL.md +240 -10
- package/skills/launchpad-deploy-status/SKILL.md +111 -9
- package/skills/launchpad-destroy/SKILL.md +41 -8
- package/skills/launchpad-identity/SKILL.md +31 -1
- package/skills/launchpad-ingest/SKILL.md +11 -6
- package/skills/launchpad-integration-contract/SKILL.md +1 -1
- package/skills/launchpad-onboard/SKILL.md +21 -1
- package/skills/launchpad-report/SKILL.md +1 -1
- package/skills/launchpad-status/SKILL.md +13 -5
package/dist/http/errors.d.ts
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
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`**
|
|
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`**
|
|
386
|
-
re-
|
|
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.
|
|
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`
|
|
340
|
-
|
|
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
|
|
485
|
+
launchpad secrets push --yes
|
|
486
|
+
launchpad secrets status
|
|
354
487
|
```
|
|
355
488
|
|
|
356
|
-
|
|
357
|
-
|
|
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**
|
|
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.
|