@mesh-tech/mesh-cli 0.1.0 → 0.12.0

package/templates/api-auth/skills/develop/SKILL.md.hbs

@@ -0,0 +1,32 @@
+---
+name: develop-{{name}}
+description: Run, extend, and deploy the {{name}} authenticated API — local 401/200/403 proof, adding resources/actions to the authz schema, gated routes.
+---
+
+# Developing {{name}}
+
+## Run locally + prove auth (zero cloud access)
+
+```bash
+mesh start && mesh login local && pnpm install && mesh dev
+```
+
+Then the README's curl sequence: `/health` open → `/api/me` 401 without / 200 with the `mesh login local` token → `/api/report` 403 until `pnpm seed:authz -- <sub>` grants `report:view` → 200. Grants are per-subject in SpiceDB — `ops@local.mesh` stays 403.
+
+## Add a gated resource or action
+
+1. Extend `api/src/schema.ts` (`defineSchema`): add the resource/action/relation. The schema is the single source of truth — never hand-roll checks.
+2. Gate the route: `app.get("/api/thing/:id", m.require("thing", "view"), …)` (the `:id` param is the resource id by default).
+3. Re-run `pnpm seed:authz` (it rewrites the compiled SpiceDB schema), grant relations with the provider's `writeRelationship`, and re-curl.
+
+## Auth planes
+
+- **authn** (`@mesh-tech/authn`, zitadel-jwt): who is calling — `requireAuth()` on `/api/*`, `publicRoute()` for open routes. Issuer comes from `ZITADEL_ISSUER` (mesh dev injects it, local or tethered).
+- **authz** (`@mesh-tech/authz`): what they may do — `m.require(resource, action)` backed by SpiceDB (`SPICEDB_HTTP_ENDPOINT`/`SPICEDB_PRESHARED_KEY`).
+- **Deployed edge**: the Service also runs behind the platform oauth2-proxy (`auth:` block in `index.ts`, needs `{{name}}:authClientId`/`authClientSecret` stack config).
+
+## Deploy
+
+```bash
+mesh login {{tenant}}.dev && mesh deploy up --yes
+```

package/templates/api-role-gating/AGENTS.md.hbs

@@ -0,0 +1,20 @@
+# Agent guidance — {{name}} (role-gating API)
+
+- Invoke the CLI as `pnpm mesh <cmd>` or (cwd-independent) `pnpm exec mesh <cmd>`.
+  Operations are `mesh` commands, never raw `aws`/`pulumi`/`kubectl`.
+- This app is **role-gating**: authorization is a coarse-role check on the
+  caller's Zitadel project roles, enforced in-process. There is NO SpiceDB — do
+  not add one (the `AppAuthzPointer` guard fails the deploy if you do).
+- Authorization vocabulary lives ONLY in `api/src/schema.ts` (`coarseRoles`).
+  Routes enforce it with `m.requireRole("<role>")` — never hand-roll role checks.
+  The same `coarseRoles` become the app's Zitadel project roles in `index.ts`.
+- **Two non-negotiables for role-gating apps (already wired — keep them):**
+  1. `api/package.json` build MUST be `esm-bundle …`, not `tsc` — plain `tsc`
+     ships bare `@mesh-tech/*` imports the container can't resolve.
+  2. `index.ts` MUST `Export` `compileOpsHubMetadata(schema)` and pass
+     `opsHubMetadataRef` to `AppAuthzPointer`, or the Hub create-key wizard
+     409s (`METADATA_UNPUBLISHED`).
+- Machine/API-key callers carry roles under the project-id-keyed Zitadel claim;
+  `authn.ts` passes `projectId` to `zitadelJwtScheme` so it reads the right key.
+- Pattern skills for authn/authz ship inside those packages (TanStack Intent
+  discovers them after `pnpm install`).

package/templates/api-role-gating/Pulumi.dev.yaml.hbs

@@ -0,0 +1,8 @@
+config:
+  aws:region: us-east-2
+  mesh:tenant: {{tenant}}
+  mesh:platform:
+    name: mesh
+    env: dev
+  mesh:deploy: false
+  mesh:deployerRole: arn:aws:iam::123456789012:role/{{tenant}}-dev-apps-deployer

package/templates/api-role-gating/Pulumi.yaml.hbs

@@ -0,0 +1,8 @@
+name: {{name}}
+runtime:
+  name: nodejs
+  options:
+    packagemanager: pnpm
+    nodeargs: "--import tsx"
+backend:
+  url: s3://mesh-platform-pulumi-state

package/templates/api-role-gating/README.md.hbs

@@ -0,0 +1,64 @@
+# {{titleCase name}}
+
+A **role-gating** API: authorization is a coarse-role check on the caller's
+Zitadel project roles — enforced **in-process**, no SpiceDB. This is the
+`role-gating` counterpart to the `api-auth` (policy-engine) template.
+
+- `@mesh-tech/authn` (Zitadel JWT) — who is calling.
+- `@mesh-tech/authz` with `zitadelRoleProvider()` — `m.requireRole("<role>")`,
+  resolved from the roles that rode in on the token.
+
+## Routes
+
+| Route      | Requires            |
+|------------|---------------------|
+| `/health`  | nothing (open)      |
+| `/admin`   | role `admin`        |
+| `/reports` | role `viewer`       |
+
+Roles are declared once in `api/src/schema.ts` (`coarseRoles`) and become the
+app's Zitadel **project roles** (see `index.ts`).
+
+## Run it locally
+
+```bash
+mesh start            # local platform (seeded Zitadel)
+pnpm install
+mesh dev              # wires the api to the local platform
+```
+
+## Two things a role-gating app MUST do (baked in here)
+
+1. **`esm-bundle` build, not `tsc`.** `api/package.json` builds with
+   `esm-bundle src/main.ts --outfile dist/main.js` — plain `tsc` leaves bare
+   `@mesh-tech/*` workspace imports unresolvable in the container
+   (`ERR_MODULE_NOT_FOUND` / CrashLoopBackOff).
+2. **Publish ops-hub metadata.** `index.ts` exports `compileOpsHubMetadata(schema)`
+   at the conventional path and threads `opsHubMetadataRef` into
+   `AppAuthzPointer`. Without it the Hub's create-key wizard hard-409s
+   (`METADATA_UNPUBLISHED`) — a role-gating app has no `SpiceDBSchema` component
+   to publish the blob for it.
+
+## Add or change roles
+
+Edit `coarseRoles` in `api/src/schema.ts`, gate routes with
+`m.requireRole("<role>")`, and redeploy — `ZitadelAppIdentity` re-syncs the
+project roles and the ops-hub metadata republishes automatically.
+
+## Deploy
+
+```bash
+mesh login {{tenant}}.dev && mesh deploy up --yes
+```
+
+The target platform must have Zitadel enabled (the `ZitadelConnector` reads it
+at preview time).
+
+## Layout
+
+- `index.ts` — Pulumi program (identity + roles, Service, ops-hub metadata,
+  `AppAuthzPointer` mode `role-gating`)
+- `api/src/main.ts` — Hono app: authn middleware + `m.requireRole(...)`
+- `api/src/schema.ts` — the authz schema (single source of truth; `coarseRoles`)
+- `api/src/authn.ts` — Zitadel JWT scheme (project-id-keyed roles claim)
+- `api/src/authz.ts` — in-process `zitadelRoleProvider()`

package/templates/api-role-gating/api/Dockerfile

@@ -0,0 +1,17 @@
+# NOTE: mesh.apps.Service auto-builds pnpm-workspace apps on the host and
+# generates its own Docker context — this Dockerfile is a fallback for manual
+# builds. The build needs devDeps (esm-bundle bundles workspace imports into a
+# single file), so install ALL deps, not --omit=dev.
+FROM node:20-slim
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+EXPOSE 3000
+
+CMD ["node", "dist/main.js"]

package/templates/api-role-gating/api/package.json.hbs

@@ -0,0 +1,28 @@
+{
+  "name": "{{name}}-api",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/main.ts",
+    "./schema": "./src/schema.ts"
+  },
+  "scripts": {
+    "dev": "tsx watch src/main.ts",
+    "start": "node dist/main.js",
+    "build": "esm-bundle src/main.ts --outfile dist/main.js",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mesh-tech/authn": "latest",
+    "@mesh-tech/authz": "latest",
+    "hono": "^4.0.0",
+    "@hono/node-server": "^1.0.0"
+  },
+  "devDependencies": {
+    "@mesh-tech/esm-bundle": "latest",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/templates/api-role-gating/api/src/authn.ts.hbs

@@ -0,0 +1,29 @@
+/**
+ * L1 authn — Zitadel JWT (@mesh-tech/authn).
+ *
+ * `projectId` (the app's own Zitadel project id / token audience) is passed so
+ * the scheme reads the PROJECT-ID-KEYED roles claim
+ * (`urn:zitadel:iam:org:project:${projectId}:roles`) that machine
+ * (client-credentials / API-key) tokens actually carry — the generic claim is
+ * empty for those, so wiring the wrong key silently 403s every gated route
+ * (MESH-2288 / MESH-2282). Fails closed when unconfigured.
+ */
+import { createAuthn, type Authn, type AuthnScheme } from "@mesh-tech/authn";
+import { zitadelJwtScheme } from "@mesh-tech/authn/schemes/zitadel-jwt";
+
+export const createAuthnFromEnv = (env: NodeJS.ProcessEnv = process.env): Authn | undefined => {
+  const schemes: Record<string, AuthnScheme> = {};
+  if (env.ZITADEL_ISSUER) {
+    const audience = env.ZITADEL_AUDIENCE ?? env.ZITADEL_PROJECT_ID;
+    if (!audience) throw new Error("{{name}} authn: ZITADEL_ISSUER set but no ZITADEL_PROJECT_ID/ZITADEL_AUDIENCE");
+    // The app knows its own project id (== audience here); let the scheme derive
+    // the exact project-scoped roles claim from it.
+    const projectId = env.ZITADEL_PROJECT_ID ?? audience;
+    schemes["zitadel-jwt"] = zitadelJwtScheme({
+      issuer: env.ZITADEL_ISSUER,
+      audience,
+      projectId,
+    });
+  }
+  return Object.keys(schemes).length > 0 ? createAuthn({ schemes }) : undefined;
+};

package/templates/api-role-gating/api/src/authz.ts.hbs

@@ -0,0 +1,12 @@
+/**
+ * L2 authz — role-gating (@mesh-tech/authz).
+ *
+ * `zitadelRoleProvider` resolves checks IN-PROCESS from the verified JWT's
+ * project roles — no SpiceDB, no metadata fetcher, no network dependency
+ * (authz spec §2). Routes gate with `m.requireRole("<role>")`.
+ */
+import { createAuthz, zitadelRoleProvider } from "@mesh-tech/authz/runtime";
+import schema from "./schema.js";
+
+export const createAppAuthz = () =>
+  createAuthz({ schemas: { "{{name}}": { schema, provider: zitadelRoleProvider() } } });

package/templates/api-role-gating/api/src/main.ts.hbs

@@ -0,0 +1,58 @@
+/**
+ * {{titleCase name}} api — role-gating reference (authz mode "role-gating").
+ *   L1 authn: Zitadel JWT (audience = this app's project).
+ *   L2 authz: `requireRole` against the roles that rode in on the token.
+ *
+ * `deps.testAuth` swaps L1 for a fixed principal in unit tests; production
+ * always runs the real scheme (fail-closed 401 when unconfigured).
+ */
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { createAuthnMiddleware, type AuthnVariables } from "@mesh-tech/authn/hono";
+import { createAuthzMiddleware, type AuthzVariables } from "@mesh-tech/authz/hono";
+import { createAuthnFromEnv } from "./authn.js";
+import { createAppAuthz } from "./authz.js";
+
+type TestAuth = { subjectSub: string; coarseRole?: string | readonly string[] };
+type AppEnv = { Variables: AuthnVariables & AuthzVariables };
+
+/** The role-gated route paths (kept in one place so authn + authz agree). */
+const GATED = ["/admin", "/reports"] as const;
+
+export const createApp = (deps: { testAuth?: TestAuth } = {}) => {
+  const app = new Hono<AppEnv>();
+  const m = createAuthzMiddleware(createAppAuthz());
+
+  // Open: no token needed.
+  app.get("/health", (c) => c.json({ ok: true, app: "{{name}}", mode: "role-gating" }));
+
+  if (deps.testAuth) {
+    const testAuth = deps.testAuth;
+    app.use("*", async (c, next) => {
+      c.set("auth", { scheme: "test", authenticatedAt: Date.now(), ...testAuth });
+      await next();
+    });
+  } else {
+    const authn = createAuthnFromEnv();
+    if (authn) {
+      const { middleware } = createAuthnMiddleware(authn);
+      for (const path of GATED) app.use(path, middleware());
+    } else {
+      // Fail closed: no authn configured → every gated route is 401, never open.
+      for (const path of GATED) app.use(path, (c) => c.json({ error: "authn unconfigured" }, 401));
+    }
+  }
+  app.use("*", m.authContextMiddleware());
+
+  // Role-gated: the caller's Zitadel project roles must include the named role.
+  app.get("/admin", m.requireRole("admin"), (c) => c.json({ ok: true, role: "admin" }));
+  app.get("/reports", m.requireRole("viewer"), (c) => c.json({ reports: [], role: "viewer" }));
+
+  return app;
+};
+
+if (process.env.NODE_ENV !== "test" && process.argv[1]?.endsWith("main.js")) {
+  const port = Number(process.env.PORT ?? 3000);
+  serve({ fetch: createApp().fetch, port });
+  console.log(`{{name}} api listening on :${port} (role-gating)`);
+}

package/templates/api-role-gating/api/src/schema.ts.hbs

@@ -0,0 +1,22 @@
+/**
+ * Authorization schema — the single source of truth (@mesh-tech/authz).
+ *
+ * mode "role-gating": enforcement is a coarse-role check on the caller's
+ * Zitadel project roles (no SpiceDB, no resources/relations). `coarseRoles` is
+ * the whole vocabulary — it becomes the app's Zitadel PROJECT ROLES (declared
+ * in `index.ts`), what the Hub create-key wizard lists, and what
+ * `m.requireRole(...)` checks against at request time.
+ *
+ * Exported as the DEFAULT export so both the api runtime (`authz.ts`) and the
+ * Pulumi program (`index.ts`, for `compileOpsHubMetadata`) import the same
+ * definition.
+ */
+
+import { defineSchema } from "@mesh-tech/authz/schema";
+
+export default defineSchema({
+  namespace: "{{name}}",
+  version: "0.1.0",
+  mode: "role-gating",
+  coarseRoles: ["admin", "viewer"] as const,
+});

package/templates/api-role-gating/api/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}

package/templates/api-role-gating/index.ts.hbs

@@ -0,0 +1,107 @@
+/**
+ * {{titleCase name}} — role-gating API (authz mode "role-gating", MESH-2278).
+ *
+ * Authorization is enforced IN-PROCESS from the Zitadel JWT's project roles —
+ * there is NO SpiceDB. The app declares its coarse roles as Zitadel PROJECT
+ * ROLES (so API keys can be granted them), publishes its ops-hub metadata
+ * (required — the Hub create-key wizard 409s without it), and broadcasts
+ * mode "role-gating". Counterpart to the `api-auth` (policy-engine) template.
+ *
+ * Wires, IN ORDER:
+ *   1. ZitadelConnector   — authed provider for the platform Zitadel.
+ *   2. ZitadelAppIdentity — this app's OWN project; roles = schema.coarseRoles
+ *                           (roleAssertion defaults ON so granted roles ride in
+ *                           tokens — essential; there is no SpiceDB fallback).
+ *   3. AppEnvironment     — namespace + providers, bound to the app's project.
+ *   4. api Service        — Hono app gating routes by role, in-process.
+ *   5. ops-hub metadata   — the compiled schema blob (coarseRoles + mode).
+ *   6. AppAuthzPointer    — mode "role-gating"; guard fails deploy if SpiceDB.
+ *
+ * Prerequisite: the target platform must have Zitadel enabled — ZitadelConnector
+ * eager-reads it at preview time.
+ *
+ * Local:  mesh start && mesh dev
+ * Deploy: mesh deploy up
+ */
+import * as pulumi from "@pulumi/pulumi";
+import { mesh } from "@mesh-tech/app-kit";
+import { compileOpsHubMetadata } from "@mesh-tech/authz";
+import type { OpsHubMetadata } from "@mesh-tech/authz";
+// The authz schema is the single source of truth, shared by the api (enforces
+// it) and this Pulumi program (compiles it to ops-hub metadata + Zitadel roles).
+import schemaDef from "./api/src/schema.js";
+
+const { tenant, platform, stack, deploy } = mesh.apps.getConfig(pulumi);
+const appName = "{{name}}";
+
+// --- 1. Connector — authed provider for the platform Zitadel. ---
+const connector = new mesh.auth.ZitadelConnector("idp", { tenant, env: platform.env });
+
+// --- 2. App identity — this app's OWN Zitadel project + roles. ---
+// The schema's coarse roles become Zitadel PROJECT ROLES: the vocabulary the
+// api-keys control plane grants against and the Hub create-key wizard lists.
+// roleAssertion defaults ON (roles are declared) so granted roles ride in the
+// token — without it a minted API key authenticates but carries no roles, which
+// is fatal for role-gating (no SpiceDB fallback).
+const identity = new mesh.auth.ZitadelAppIdentity("identity", {
+  connector,
+  tenant,
+  env: platform.env,
+  project: { name: appName },
+  roles: [...schemaDef.coarseRoles],
+  applications: {
+    api: { type: "api" },
+  },
+});
+
+// --- 3. Environment — bound to the app's own project via zitadelAppProjectId. ---
+const env = new mesh.apps.AppEnvironment("env", {
+  tenant,
+  platform,
+  stack,
+  deploy,
+  appName,
+  namespace: true,
+  database: false,
+  zitadelAppProjectId: identity.projectId,
+});
+
+// --- 4. api Service — in-process authn + role check; no oauth2-proxy, no SpiceDB. ---
+const api = new mesh.apps.Service("api", {
+  env,
+  runtime: "node",
+  src: "./api",
+  port: 3000,
+  environment: {
+    ZITADEL_ISSUER: pulumi.output(env.zitadel).apply((z) => z?.issuer ?? ""),
+    ZITADEL_PROJECT_ID: identity.projectId,
+  },
+  ingress: env.buildIngress({
+    subdomain: "{{name}}-api",
+    healthCheckPath: "/health",
+  }),
+  replicas: 1,
+  resources: { cpu: "100m", memory: "128Mi" },
+});
+
+// --- 5. Ops-hub metadata — MANDATORY for role-gating apps. ---
+// The Hub create-key path validates requested roles against the PUBLISHED
+// coarseRoles and hard-409s (METADATA_UNPUBLISHED) without it. Role-gating apps
+// have no SpiceDBSchema component to export it, so publish the compiled blob
+// directly at the conventional path the Hub assembler sweeps.
+const opsHubMetadataRef = `/mesh-platform/${tenant}/${platform.env}/apps/${appName}/stacks/${stack}/authz/ops-hub-metadata`;
+new mesh.exports.Export<OpsHubMetadata>("ops-hub-metadata", {
+  path: opsHubMetadataRef,
+  value: compileOpsHubMetadata(schemaDef),
+});
+
+// --- 6. AppAuthzPointer — LAST. mode "role-gating" tells Ops Hub to render the
+// role-gating surface; its guard fails the deploy if any SpiceDB is registered. ---
+new mesh.auth.AppAuthzPointer("authz", { env, mode: "role-gating", opsHubMetadataRef });
+
+export const app = env.register({
+  description: "{{titleCase name}} — role-gating API (roles enforced in-process from the Zitadel JWT)",
+});
+
+/** The app's own Zitadel project id (grant API keys against this). */
+export const zitadelProjectId = identity.projectId;

package/templates/api-role-gating/package.json.hbs

@@ -0,0 +1,21 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@10.29.2",
+  "keywords": ["tanstack-intent"],
+  "scripts": {
+    "mesh": "mesh",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mesh-tech/app-kit": "latest",
+    "@mesh-tech/authz": "latest",
+    "@pulumi/pulumi": "^3.214.1"
+  },
+  "devDependencies": {
+    "tsx": "^4.20.4",
+    "typescript": "^5.7.2"
+  }
+}

package/templates/api-role-gating/skills/develop/SKILL.md.hbs

@@ -0,0 +1,60 @@
+---
+name: develop-{{name}}
+description: Run, extend, and deploy the {{name}} role-gating API — coarse-role checks on Zitadel project roles (no SpiceDB), esm-bundle build, mandatory ops-hub metadata export.
+---
+
+# Developing {{name}} (role-gating)
+
+This app enforces authorization as a **coarse-role check** on the caller's
+Zitadel project roles, **in-process** — no SpiceDB. Roles are declared once in
+`api/src/schema.ts` and become the app's Zitadel project roles in `index.ts`.
+
+## Run locally
+
+```bash
+mesh start && pnpm install && mesh dev
+```
+
+`/health` is open; `/admin` needs role `admin`; `/reports` needs role `viewer`.
+A token without the role → 403; no/invalid token on a gated route → 401.
+
+## Add or change a role-gated route
+
+1. Add the role to `coarseRoles` in `api/src/schema.ts`.
+2. Gate the route: `app.get("/thing", m.requireRole("<role>"), …)` and add its
+   path to the `GATED` list in `api/src/main.ts` (so authn runs on it too).
+3. Redeploy — `ZitadelAppIdentity` re-syncs the project roles and the ops-hub
+   metadata republishes.
+
+## Two role-gating gotchas (already wired — do NOT regress)
+
+Both were discovered the hard way (MESH-2282) and each costs a redeploy:
+
+1. **`esm-bundle` build, not `tsc`.** `api/package.json`:
+   `"build": "esm-bundle src/main.ts --outfile dist/main.js"` with the
+   `@mesh-tech/esm-bundle` devDep. Plain `tsc` leaves bare `@mesh-tech/*`
+   workspace imports unresolvable in the Service container
+   (`ERR_MODULE_NOT_FOUND` / CrashLoopBackOff).
+2. **Publish ops-hub metadata.** `index.ts` does
+   `mesh.exports.Export(compileOpsHubMetadata(schema))` at
+   `…/apps/{{name}}/stacks/{stack}/authz/ops-hub-metadata` and passes that
+   `opsHubMetadataRef` to `AppAuthzPointer`. A role-gating app has no
+   `SpiceDBSchema` component to publish this, and the Hub create-key wizard
+   hard-409s (`METADATA_UNPUBLISHED`) without it — it validates requested roles
+   against the app's PUBLISHED `coarseRoles`.
+
+## Never add SpiceDB
+
+`AppAuthzPointer({ mode: "role-gating" })` trips a deploy-time guard if any
+SpiceDB instance is registered. Role-gating means roles are the whole authz
+story; for resource/relation-level rules use the `api-auth` (policy-engine)
+template instead.
+
+## Deploy
+
+```bash
+mesh login {{tenant}}.dev && mesh deploy up --yes
+```
+
+The target platform must have Zitadel enabled — `ZitadelConnector` reads it at
+preview time.

package/templates/api-role-gating/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}

package/templates/apps-repo/README.md.hbs

@@ -0,0 +1,24 @@
+# {{repoName}}
+
+{{tenantTitle}} applications deployed on the Mesh platform (app tenant: `{{tenant}}`).
+
+Each directory under `apps/` is an independent Pulumi project scaffolded with
+`mesh create-app`.
+
+## Setup
+
+```bash
+mesh registry login          # CodeArtifact token for @mesh-tech packages
+pnpm install
+mesh init app-tenant --tenant {{tenant}}   # the doctor — checks auth, registry, tenant registration, repo shape
+```
+
+## Adding an app
+
+```bash
+mesh create-app --tenant {{tenant}} --name my-app --primitives service
+cd apps/my-app
+pnpm install
+mesh dev                     # run locally
+mesh deploy up               # deploy via the stack's deployer role
+```

package/templates/apps-repo/gitignore

@@ -0,0 +1,41 @@
+# Dependencies
+node_modules
+
+# Build output
+dist/
+build/
+.deploy/
+
+# Local secret material — never commit (credential values live in Secrets Manager)
+data.json
+*-creds.json
+creds*.json
+secrets*.json
+
+# Misc
+.DS_Store
+*.pem
+.env
+.env.*
+!.env.example
+.envrc
+
+# Local files
+*.local
+*.local.*
+
+# Debug
+logs/
+npm-debug.log*
+pnpm-debug.log*
+
+# TypeScript
+*.tsbuildinfo
+
+# Pulumi
+.pulumi/
+# Personal dev stacks (never commit) — keep the shared dev/prod stacks
+Pulumi.dev-*.yaml
+
+# Temporary
+temp/

package/templates/apps-repo/npmrc.hbs

@@ -0,0 +1,7 @@
+# CodeArtifact registry for @mesh-tech scoped packages.
+#
+# This file contains ONLY the registry URL — never the auth token.
+# The auth token lives in ~/.npmrc, written by:
+#   mesh registry login
+#
+@mesh-tech:registry={{registryUrl}}

package/templates/apps-repo/package.json.hbs

@@ -0,0 +1,15 @@
+{
+  "name": "{{repoName}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "description": "{{tenantTitle}} applications deployed on the Mesh platform",
+  "packageManager": "pnpm@10.29.2",
+  "scripts": {
+    "mesh": "mesh",
+    "typecheck": "pnpm -r typecheck"
+  },
+  "devDependencies": {
+    "@mesh-tech/mesh-cli": "latest"
+  }
+}

package/templates/apps-repo/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+# Workspace packages — each app is an independent Pulumi project
+packages:
+  - apps/*

package/templates/apps-repo/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "."
+  },
+  "exclude": ["node_modules", "dist"]
+}

package/templates/external-service/AGENTS.md.hbs

@@ -0,0 +1,20 @@
+# Agent guidance — {{name}}
+
+- Invoke the CLI as `pnpm mesh <cmd>` or (cwd-independent) `pnpm exec mesh <cmd>` —
+  a `"mesh"` script + the bundled `@mesh-tech/*` dep make both work after
+  `pnpm install`. For a bare `mesh` on PATH, run once: `pnpm exec mesh install-shim`.
+- Operations are `mesh` commands, never raw `aws`/`pulumi`/`kubectl`:
+  `mesh start` (local platform), `mesh dev --externals` (run services +
+  vendor mock), `mesh login`, `mesh deploy`, `mesh secrets set`.
+- Local loop needs zero cloud access: `mesh start && mesh dev --externals`, then
+  `curl -X POST localhost:3000/payments/quote -d '{"amount":125.5}'`.
+- Credentials are NEVER in code/env/config: declare fields on the
+  `ExternalService` (index.ts), read them at runtime with
+  `resolveCredentials("vendorpay")`. Real values: `mesh secrets set
+  external/vendorpay`; local values: seeded automatically by `mesh dev
+  --externals` from the `mesh.externals` declaration in package.json.
+- Vendor HTTP calls go through `@mesh-tech/http-client` (`enhanceFetch`) for
+  correlation-id propagation and structured request logs.
+- Pattern skills for the SDKs used here ship inside the `@mesh-tech/*`
+  packages (discoverable via TanStack Intent after `pnpm install`).
+- This app's own skill lives at `skills/develop/SKILL.md`.