@oneteam-app/apps-cli 0.0.0-stage → 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @oneteam-app/apps-cli
+
+## 0.1.0-alpha.1
+
+- Depends on `@oneteam-app/apps@0.1.0-alpha.1`.
+
+## 0.1.0-alpha.0
+
+- First alpha.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oneteam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @oneteam-app/apps-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Adds Oneteam login to a Next.js App Router project and checks the setup.
+
+> **Alpha.** Expect changes before 1.0.
+
+```bash
+npx @oneteam-app/apps-cli init --url https://your-app.example.com
+npx @oneteam-app/apps-cli validate
+npx @oneteam-app/apps-cli doctor
+```
+
+| Command | Does |
+|---|---|
+| `init` | Writes `lib/oneteam.ts`, the auth route handler, a deny-by-default `proxy.ts`, `oneteam.app.json`, `.env.example` entries, and the rules coding agents read (`AGENTS.md`, a Cursor rule). Never overwrites existing files without `--force`, and never replaces an existing middleware |
+| `validate` | Checks `oneteam.app.json` against the manifest schema |
+| `doctor` | Checks the manifest, environment variables, route protection and that the Oneteam issuer is reachable. Use `--offline` to skip the network check |
+
+Non-interactive by design, so AI coding tools can run it.
+
+Documentation: https://github.com/FlexAppeal/oneteam-apps
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { parseArgs } from "util";
+
+// src/commands.ts
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { basename, dirname, join, relative, sep } from "path";
+import { validateManifest } from "@oneteam-app/apps/contracts";
+
+// src/generated/instructions.ts
+var AGENT_INSTRUCTIONS = "# Oneteam login and authorization\n\nApps built this way are opened from a Oneteam shortcut. Oneteam signs the\nemployee in (no extra password) and tells the app who they are and which\nOneteam permissions they hold. Authorization is RBAC on those permissions:\nadmins grant them through Oneteam roles, and the app checks them by name\n(`network::users.update`). Apps have no permissions or roles of their own.\n\n**Supported today**, with `@oneteam-app/apps`:\n\n- **TanStack Start** (Lovable's default, also on Cloudflare Workers): `@oneteam-app/apps/tanstack-start`\n- **Next.js App Router** (Next 15.2+, 16 recommended): `@oneteam-app/apps/next`\n\nOn any other stack, stop and tell the user it isn't supported yet.\n\n## Never hand-roll this\n\nWriting the OAuth flow by hand is the main way apps get this wrong: PKCE with\n`plain`, no `state` check, an ID token read with `atob` instead of verified,\ntokens in `localStorage`. Use the package, which does the whole flow in one\ncall, or stop and say it isn't supported on this stack.\n\n## Rules\n\nThese are not style preferences. Breaking one creates a security hole.\n\n- **Deny by default.** Next.js: `proxy.ts` runs `oneteam.proxy()` for every route.\n  TanStack Start: `src/start.ts` has a request middleware that calls\n  `oneteam.guard()`. Add to `publicPaths` only what anyone on the internet may\n  open (health checks, a public landing page), and ask the user first.\n- **Never exclude routes from the gate by file extension.** `/api/receipts/1.jpg`\n  is data. Keep the scaffolded matcher; put public files in `public/assets/`\n  and add `'/assets/*'` to `publicPaths`.\n- **The gate is a safety net, not the check.** Server actions, server functions\n  and route handlers still call `requirePermission` / `protectRoute` themselves.\n- **Check permissions on the server, every time.** Everything that reads or\n  changes protected data runs on the server (Next.js server action or route\n  handler, TanStack Start server function or server route) and calls\n  `oneteam.requirePermission(...)` (or uses `oneteam.protectRoute`). `<Protected>`\n  and `useOneteam().can` only hide UI.\n- **Never trust ids from the browser for authorization.** Load the record\n  first, then check against *its* community/owner:\n  `requirePermission('network::users.update', { communityId: expense.communityId })`.\n  Scope list queries with `oneteam.communitiesFor(session, permission)`.\n- **Identify users by `session.user.id`** (Oneteam user id) or\n  `session.user.externalId` (employee number). Not by email, not by `sub`,\n  never by a user id sent in a request body.\n- **Secrets stay on the server.** Never prefix `ONETEAM_CLIENT_SECRET` or\n  `ONETEAM_SESSION_SECRET` with `NEXT_PUBLIC_` or `VITE_`, never put them in code,\n  never log tokens or sessions, never pass `getAccessToken()` results to the browser.\n  TanStack Start: import `oneteam.server.ts` only from server functions, server\n  routes and `src/start.ts`.\n- **Don't build your own login.** No custom JWT parsing, no reading tokens from\n  query strings, no localStorage tokens, no second login screen.\n- **Authorize on Oneteam permissions only.** Not on a role, an admin flag, a\n  function name, an email domain or a hard-coded list of user ids. Pick each\n  permission from `node_modules/@oneteam-app/apps/docs/oneteam-permissions.md`\n  (typed as `OneteamPermission`, so a wrong name doesn't compile) and name the\n  ones the app uses once, e.g. in `lib/permissions.ts`. Never invent a name or\n  match on a prefix.\n- **Community permissions are not organisation-wide.** A `network:` permission\n  without `communityId` is only true for users who hold the same action\n  organisation-wide. That's intended: don't \"fix\" it by dropping the community check.\n\n## The shape of a protected app\n\nTanStack Start (Lovable): full files in [references/tanstack-start.md](references/tanstack-start.md).\n\n```ts\n// src/lib/oneteam.server.ts\nimport { createOneteam } from '@oneteam-app/apps/tanstack-start';\nimport manifest from '../../oneteam.app.json';\nexport const oneteam = createOneteam({ scopes: manifest.scopes });\n\n// src/routes/api/oneteam/$.ts\nexport const Route = createFileRoute('/api/oneteam/$')({ server: { handlers: oneteam.handlers } });\n\n// src/start.ts \u2014 deny by default\nconst oneteamMiddleware = createMiddleware().server((ctx) => oneteam.guard(ctx, { publicPaths: ['/health'] }));\nexport const startInstance = createStart(() => ({ requestMiddleware: [oneteamMiddleware] }));\n\n// any server function that touches protected data\nexport const approveExpense = createServerFn({ method: 'POST' })\n  .validator((id: string) => id)\n  .handler(async ({ data: id }) => {\n    const expense = await db.expense.findUniqueOrThrow({ where: { id } });\n    await oneteam.requirePermission(APPROVE_EXPENSES, { communityId: expense.communityId });\n    // ...\n  });\n```\n\nNext.js:\n\n```ts\n// lib/oneteam.ts\nimport { createOneteam } from '@oneteam-app/apps/next';\nimport manifest from '../oneteam.app.json';\nexport const oneteam = createOneteam({ scopes: manifest.scopes });\n\n// proxy.ts \u2014 deny by default\nexport const proxy = oneteam.proxy({ publicPaths: ['/health'] });\n\n// app/api/oneteam/[...oneteam]/route.ts\nexport const { GET, POST } = oneteam.handlers;\n\n// lib/permissions.ts \u2014 the Oneteam permissions this app checks\nexport const APPROVE_EXPENSES = 'network::users.update' satisfies OneteamPermission;\n\n// any server action or route handler that touches protected data\nconst expense = await db.expense.findUniqueOrThrow({ where: { id } });\nawait oneteam.requirePermission(APPROVE_EXPENSES, { communityId: expense.communityId });\n```\n\n## Workflow\n\nDo these in order. Don't skip the checks at the end.\n\n1. **Confirm the stack.** TanStack Start: `package.json` has `@tanstack/react-start`\n   and there is a `src/routes/` directory. Next.js: `package.json` has `next` and\n   there is an `app/` or `src/app/` directory.\n2. **Scaffold.**\n   ```bash\n   npm install @oneteam-app/apps\n   npx @oneteam-app/apps-cli init --url https://<production-domain>\n   ```\n   Ask the user for the production domain if you don't know it. Never guess one,\n   and never use a preview URL (`*.vercel.app` previews, Lovable's editor preview)\n   as the production domain; a published `https://<name>.lovable.app` is fine.\n   `init` creates the setup files of [references/tanstack-start.md](references/tanstack-start.md)\n   or [references/nextjs.md](references/nextjs.md), `oneteam.app.json` and\n   `.env.example` entries. It won't overwrite an existing `src/start.ts`,\n   `middleware.ts` or `proxy.ts`: add the gate to it yourself.\n   **Without a terminal (Lovable):** add `@oneteam-app/apps` as a dependency and\n   create those files yourself, exactly as in the reference.\n3. **Declare what the app needs** in `oneteam.app.json` `scopes`:\n   `oneteam:permissions` (scaffolded) for permission checks, `oneteam:communities`\n   for memberships and for permissions per community, `oneteam:functions` for\n   functions, `oneteam:organisation` for the employee number. Request only what\n   the app uses; admins see and approve each one. Then run\n   `npx @oneteam-app/apps-cli validate`.\n4. **Choose the permissions.** For each action not every employee may do, pick\n   the Oneteam permission whose holders should be allowed, from\n   `node_modules/@oneteam-app/apps/docs/oneteam-permissions.md`: its \"Granted by\"\n   column is the role editor toggle admins use. Use a `network:` permission when\n   the action belongs to a store/location/team, an `organisation:` one when it is\n   organisation-wide. Tell the user which permissions you chose and why.\n5. **Protect the app** following [references/tanstack-start.md](references/tanstack-start.md)\n   or [references/nextjs.md](references/nextjs.md) and the rules above.\n6. **Register the app.** With the Oneteam MCP connector, an organisation admin\n   can do it from this chat: call `register_app` with the app's production URL\n   (and its localhost URL). Otherwise an admin registers it in the Oneteam\n   dashboard. Either way the app starts in development status (only the person\n   who registered it can sign in) and comes with a client id and secret. The user\n   stores them as server-side secrets themselves (Lovable: project secrets;\n   otherwise `.env.local` and the hosting provider's secret settings); never ask them to paste the secret into the chat, and never\n   repeat a secret you were shown.\n7. **Verify:** `npx @oneteam-app/apps-cli doctor`, `npm run build`, then walk\n   through [references/checklist.md](references/checklist.md) and report the\n   result to the user.\n\n## What you cannot do for the user\n\nSay these plainly instead of reporting success:\n\n- Registering the app in Oneteam and getting it approved by an admin.\n- Putting the client id and secret into `.env.local` and the hosting provider.\n- Making sure the right people hold the chosen permissions through their Oneteam roles.\n\nUntil those happen, login will fail with `access_denied` or\n`not_a_oneteam_app_client`, however correct the code is.\n\n## Reference\n\n- [references/tanstack-start.md](references/tanstack-start.md): API and patterns for the TanStack Start adapter (Lovable)\n- [references/nextjs.md](references/nextjs.md): API and patterns for the Next.js adapter\n- [references/checklist.md](references/checklist.md): final security review\n- [references/oneteam-permissions.md](references/oneteam-permissions.md): every Oneteam permission name\n- Example app: `examples/next-app` in the oneteam-apps repository\n- Local testing without Oneteam: `pnpm dev:fake` in that repository";
+var CURSOR_RULE = "---\ndescription: Oneteam login and authorization rules for this app\nalwaysApply: true\n---\n\n## Never hand-roll this\n\nWriting the OAuth flow by hand is the main way apps get this wrong: PKCE with\n`plain`, no `state` check, an ID token read with `atob` instead of verified,\ntokens in `localStorage`. Use the package, which does the whole flow in one\ncall, or stop and say it isn't supported on this stack.\n\n## Rules\n\nThese are not style preferences. Breaking one creates a security hole.\n\n- **Deny by default.** Next.js: `proxy.ts` runs `oneteam.proxy()` for every route.\n  TanStack Start: `src/start.ts` has a request middleware that calls\n  `oneteam.guard()`. Add to `publicPaths` only what anyone on the internet may\n  open (health checks, a public landing page), and ask the user first.\n- **Never exclude routes from the gate by file extension.** `/api/receipts/1.jpg`\n  is data. Keep the scaffolded matcher; put public files in `public/assets/`\n  and add `'/assets/*'` to `publicPaths`.\n- **The gate is a safety net, not the check.** Server actions, server functions\n  and route handlers still call `requirePermission` / `protectRoute` themselves.\n- **Check permissions on the server, every time.** Everything that reads or\n  changes protected data runs on the server (Next.js server action or route\n  handler, TanStack Start server function or server route) and calls\n  `oneteam.requirePermission(...)` (or uses `oneteam.protectRoute`). `<Protected>`\n  and `useOneteam().can` only hide UI.\n- **Never trust ids from the browser for authorization.** Load the record\n  first, then check against *its* community/owner:\n  `requirePermission('network::users.update', { communityId: expense.communityId })`.\n  Scope list queries with `oneteam.communitiesFor(session, permission)`.\n- **Identify users by `session.user.id`** (Oneteam user id) or\n  `session.user.externalId` (employee number). Not by email, not by `sub`,\n  never by a user id sent in a request body.\n- **Secrets stay on the server.** Never prefix `ONETEAM_CLIENT_SECRET` or\n  `ONETEAM_SESSION_SECRET` with `NEXT_PUBLIC_` or `VITE_`, never put them in code,\n  never log tokens or sessions, never pass `getAccessToken()` results to the browser.\n  TanStack Start: import `oneteam.server.ts` only from server functions, server\n  routes and `src/start.ts`.\n- **Don't build your own login.** No custom JWT parsing, no reading tokens from\n  query strings, no localStorage tokens, no second login screen.\n- **Authorize on Oneteam permissions only.** Not on a role, an admin flag, a\n  function name, an email domain or a hard-coded list of user ids. Pick each\n  permission from `node_modules/@oneteam-app/apps/docs/oneteam-permissions.md`\n  (typed as `OneteamPermission`, so a wrong name doesn't compile) and name the\n  ones the app uses once, e.g. in `lib/permissions.ts`. Never invent a name or\n  match on a prefix.\n- **Community permissions are not organisation-wide.** A `network:` permission\n  without `communityId` is only true for users who hold the same action\n  organisation-wide. That's intended: don't \"fix\" it by dropping the community check.\n\n## The shape of a protected app\n\nTanStack Start (Lovable): full files in [references/tanstack-start.md](references/tanstack-start.md).\n\n```ts\n// src/lib/oneteam.server.ts\nimport { createOneteam } from '@oneteam-app/apps/tanstack-start';\nimport manifest from '../../oneteam.app.json';\nexport const oneteam = createOneteam({ scopes: manifest.scopes });\n\n// src/routes/api/oneteam/$.ts\nexport const Route = createFileRoute('/api/oneteam/$')({ server: { handlers: oneteam.handlers } });\n\n// src/start.ts \u2014 deny by default\nconst oneteamMiddleware = createMiddleware().server((ctx) => oneteam.guard(ctx, { publicPaths: ['/health'] }));\nexport const startInstance = createStart(() => ({ requestMiddleware: [oneteamMiddleware] }));\n\n// any server function that touches protected data\nexport const approveExpense = createServerFn({ method: 'POST' })\n  .validator((id: string) => id)\n  .handler(async ({ data: id }) => {\n    const expense = await db.expense.findUniqueOrThrow({ where: { id } });\n    await oneteam.requirePermission(APPROVE_EXPENSES, { communityId: expense.communityId });\n    // ...\n  });\n```\n\nNext.js:\n\n```ts\n// lib/oneteam.ts\nimport { createOneteam } from '@oneteam-app/apps/next';\nimport manifest from '../oneteam.app.json';\nexport const oneteam = createOneteam({ scopes: manifest.scopes });\n\n// proxy.ts \u2014 deny by default\nexport const proxy = oneteam.proxy({ publicPaths: ['/health'] });\n\n// app/api/oneteam/[...oneteam]/route.ts\nexport const { GET, POST } = oneteam.handlers;\n\n// lib/permissions.ts \u2014 the Oneteam permissions this app checks\nexport const APPROVE_EXPENSES = 'network::users.update' satisfies OneteamPermission;\n\n// any server action or route handler that touches protected data\nconst expense = await db.expense.findUniqueOrThrow({ where: { id } });\nawait oneteam.requirePermission(APPROVE_EXPENSES, { communityId: expense.communityId });\n```\n";
+
+// src/templates.ts
+var ENV_KEYS = [
+  { key: "ONETEAM_CLIENT_ID", comment: "From Oneteam dashboard \u2192 Settings \u2192 Apps & Shortcuts \u2192 Apps \u2192 your app" },
+  { key: "ONETEAM_CLIENT_SECRET", comment: "Server only. Never prefix with NEXT_PUBLIC_ or VITE_" },
+  { key: "ONETEAM_SESSION_SECRET", comment: "At least 32 random characters: openssl rand -base64 32" },
+  { key: "ONETEAM_APP_URL", comment: "Public base URL of this app; must match a registered redirect URI", value: "http://localhost:3000" }
+];
+function libFile(manifestImport) {
+  return `import { createOneteam } from '@oneteam-app/apps/next';
+import manifest from '${manifestImport}';
+
+// Request exactly the scopes the manifest declares (and the admin approves).
+export const oneteam = createOneteam({ scopes: manifest.scopes });
+`;
+}
+function routeFile(libImport) {
+  return `import { oneteam } from '${libImport}';
+
+export const { GET, POST } = oneteam.handlers;
+`;
+}
+function proxyFile(libImport) {
+  return `import { oneteam } from '${libImport}';
+
+// Deny by default: every route needs a Oneteam session unless listed here.
+// Only add paths that are safe for anyone on the internet to open.
+export const proxy = oneteam.proxy({
+  publicPaths: [],
+});
+
+export const config = {
+  // Only Next.js internals skip the proxy. Never exclude by file extension:
+  // /api/receipts/123.jpg is data, not a static asset. Public files go under
+  // /public/assets and are listed in publicPaths as '/assets/*'.
+  matcher: ['/((?!_next/static/|_next/image$|favicon\\\\.ico$).*)'],
+};
+`;
+}
+function manifest(name, productionUrl) {
+  const base = productionUrl?.replace(/\/+$/, "") ?? "https://REPLACE-WITH-PRODUCTION-DOMAIN";
+  return {
+    $schema: "https://oneteam.io/schemas/app.v1.json",
+    schema_version: 1,
+    name,
+    login_uri: `${base}/api/oneteam/login`,
+    redirect_uris: [`${base}/api/oneteam/callback`],
+    // oneteam:permissions: the user's Oneteam permissions, for can() / requirePermission().
+    scopes: ["openid", "profile", "email", "offline_access", "oneteam:permissions"],
+    development: {
+      login_uri: "http://localhost:3000/api/oneteam/login",
+      redirect_uris: ["http://localhost:3000/api/oneteam/callback"]
+    }
+  };
+}
+function tanstackLibFile(manifestImport) {
+  return `import { createOneteam } from '@oneteam-app/apps/tanstack-start';
+import manifest from '${manifestImport}';
+
+// Server only (.server.ts): TanStack Start keeps it out of the browser bundle.
+// Request exactly the scopes the manifest declares (and the admin approves).
+export const oneteam = createOneteam({ scopes: manifest.scopes });
+`;
+}
+function tanstackRouteFile() {
+  return `import { createFileRoute } from '@tanstack/react-router';
+import { oneteam } from '../../../lib/oneteam.server';
+
+// GET login \xB7 GET callback \xB7 GET session \xB7 POST logout
+export const Route = createFileRoute('/api/oneteam/$')({
+  server: { handlers: oneteam.handlers },
+});
+`;
+}
+function tanstackStartFile() {
+  return `import { createMiddleware, createStart } from '@tanstack/react-start';
+import { oneteam } from './lib/oneteam.server';
+
+// Deny by default: every page, server route and server function needs a
+// Oneteam session unless listed in publicPaths. Only add paths that are safe
+// for anyone on the internet to open. Inside .server() so the server-only
+// module stays out of the browser bundle.
+const oneteamMiddleware = createMiddleware().server((ctx) => oneteam.guard(ctx, { publicPaths: [] }));
+
+export const startInstance = createStart(() => ({
+  requestMiddleware: [oneteamMiddleware],
+}));
+`;
+}
+function tanstackFunctionsFile() {
+  return `import { createServerFn } from '@tanstack/react-start';
+import { oneteam } from './oneteam.server';
+
+/**
+ * Session without tokens, for <OneteamProvider session={...}>. Load it in the
+ * root route: beforeLoad: async () => ({ session: await fetchSession() }).
+ */
+export const fetchSession = createServerFn({ method: 'GET' }).handler(() => oneteam.getClientSession());
+`;
+}
+
+// src/commands.ts
+var MANIFEST_FILE = "oneteam.app.json";
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function writeProjectFile(root, path, contents) {
+  const absolute = join(root, path);
+  const realRoot = realpathSync(root);
+  const isInside = (target) => target === realRoot || target.startsWith(`${realRoot}${sep}`);
+  let existingParent = dirname(absolute);
+  while (!existsSync(existingParent)) existingParent = dirname(existingParent);
+  if (!isInside(realpathSync(existingParent))) {
+    throw new Error(`refusing to write ${path}: it resolves outside the project`);
+  }
+  mkdirSync(dirname(absolute), { recursive: true });
+  if (!isInside(realpathSync(dirname(absolute)))) {
+    throw new Error(`refusing to write ${path}: it resolves outside the project`);
+  }
+  if (existsSync(absolute) && lstatSync(absolute).isSymbolicLink()) {
+    throw new Error(`refusing to write ${path}: it is a symbolic link`);
+  }
+  writeFileSync(absolute, contents);
+}
+function writeIfMissing(root, path, contents, out2, force) {
+  const absolute = join(root, path);
+  if (existsSync(absolute) && !force) {
+    out2.warn(`skipped ${path} (already exists; use --force to overwrite)`);
+    return false;
+  }
+  writeProjectFile(root, path, contents);
+  out2.info(`created ${path}`);
+  return true;
+}
+function detectNextApp(root) {
+  const packagePath = join(root, "package.json");
+  if (!existsSync(packagePath)) return null;
+  const pkg = readJson(packagePath);
+  if (!pkg.dependencies?.next && !pkg.devDependencies?.next) return null;
+  if (existsSync(join(root, "src", "app"))) return { appDir: "src/app", srcPrefix: "src/" };
+  if (existsSync(join(root, "app"))) return { appDir: "app", srcPrefix: "" };
+  return null;
+}
+function hasDependency(root, name) {
+  const packagePath = join(root, "package.json");
+  if (!existsSync(packagePath)) return false;
+  const pkg = readJson(packagePath);
+  return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
+}
+function detectTanstackStartApp(root) {
+  return hasDependency(root, "@tanstack/react-start") && existsSync(join(root, "src", "routes"));
+}
+var AGENTS_FILE = "AGENTS.md";
+var CURSOR_RULE_FILE = ".cursor/rules/oneteam-apps.mdc";
+var AGENTS_MARKER = "<!-- oneteam-apps:start -->";
+var AGENTS_END = "<!-- oneteam-apps:end -->";
+function writeAgentInstructions(root, out2, force) {
+  const section = `${AGENTS_MARKER}
+${AGENT_INSTRUCTIONS}
+${AGENTS_END}`;
+  const agentsPath = join(root, AGENTS_FILE);
+  const existing = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : null;
+  const start = existing?.indexOf(AGENTS_MARKER) ?? -1;
+  const end = existing && start >= 0 ? existing.indexOf(AGENTS_END, start) : -1;
+  if (existing === null) {
+    writeProjectFile(root, AGENTS_FILE, `${section}
+`);
+    out2.info(`created ${AGENTS_FILE}`);
+  } else if (start >= 0 && end >= 0) {
+    writeProjectFile(root, AGENTS_FILE, `${existing.slice(0, start)}${section}${existing.slice(end + AGENTS_END.length)}`);
+    out2.info(`updated the Oneteam section in ${AGENTS_FILE}`);
+  } else {
+    if (start >= 0) out2.warn(`${AGENTS_FILE} has a Oneteam start marker without an end marker; leaving it and appending a new section`);
+    writeProjectFile(root, AGENTS_FILE, `${existing}${existing.endsWith("\n") ? "" : "\n"}
+${section}
+`);
+    out2.info(`added a Oneteam section to ${AGENTS_FILE}`);
+  }
+  writeIfMissing(root, CURSOR_RULE_FILE, CURSOR_RULE, out2, force);
+}
+function init(root, options, out2) {
+  const force = options.force ?? false;
+  const next = detectNextApp(root);
+  if (next) {
+    initNext(root, next, out2, force);
+  } else if (detectTanstackStartApp(root)) {
+    initTanstackStart(root, out2, force);
+  } else {
+    out2.error(
+      'No supported project found: Next.js App Router ("next" in package.json and an app/ or src/app/ directory) or TanStack Start ("@tanstack/react-start" in package.json and a src/routes/ directory). Other frameworks: use @oneteam-app/apps directly, see the README.'
+    );
+    return 1;
+  }
+  writeAgentInstructions(root, out2, force);
+  if (!existsSync(join(root, MANIFEST_FILE)) || force) {
+    const name = options.name ?? readJson(join(root, "package.json")).name ?? basename(root);
+    writeIfMissing(root, MANIFEST_FILE, `${JSON.stringify(manifest(name, options.url), null, 2)}
+`, out2, force);
+    if (!options.url) out2.warn(`set your production domain in ${MANIFEST_FILE} (or re-run with --url)`);
+  } else {
+    out2.warn(`skipped ${MANIFEST_FILE} (already exists)`);
+  }
+  const envPath = join(root, ".env.example");
+  const envContents = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+  const missing = ENV_KEYS.filter(({ key }) => !new RegExp(`^${key}=`, "m").test(envContents));
+  if (missing.length > 0) {
+    const block = missing.map(({ key, comment, value }) => `# ${comment}
+${key}=${value ?? ""}`).join("\n");
+    writeProjectFile(root, ".env.example", `${envContents}${envContents && !envContents.endsWith("\n") ? "\n" : ""}${block}
+`);
+    out2.info(`added ${missing.map(({ key }) => key).join(", ")} to .env.example`);
+  }
+  out2.info("");
+  out2.info("Next steps:");
+  out2.info("  1. npm install @oneteam-app/apps");
+  out2.info("  2. Register the app in Oneteam: the register_app tool of the Oneteam MCP connector (as an admin), or the dashboard");
+  out2.info("  3. Put the client id and secret in .env.local and your host's secret settings, plus ONETEAM_SESSION_SECRET");
+  out2.info("  4. npx oneteam-apps doctor");
+  return 0;
+}
+function initNext(root, next, out2, force) {
+  const libPath = `${next.srcPrefix}lib/oneteam.ts`;
+  const libImport = "@/lib/oneteam";
+  writeIfMissing(root, libPath, libFile(next.srcPrefix ? "../../oneteam.app.json" : "../oneteam.app.json"), out2, force);
+  writeIfMissing(root, `${next.appDir}/api/oneteam/[...oneteam]/route.ts`, routeFile(libImport), out2, force);
+  const existingGate = ["proxy.ts", "middleware.ts", "src/proxy.ts", "src/middleware.ts"].find(
+    (file) => existsSync(join(root, file))
+  );
+  if (existingGate && !force) {
+    out2.warn(
+      `found ${existingGate}: not replacing it. Call oneteam.proxy() from it so every route requires a session (see the example app).`
+    );
+  } else {
+    writeIfMissing(root, `${next.srcPrefix}proxy.ts`, proxyFile(libImport), out2, force);
+  }
+}
+function initTanstackStart(root, out2, force) {
+  writeIfMissing(root, "src/lib/oneteam.server.ts", tanstackLibFile("../../oneteam.app.json"), out2, force);
+  writeIfMissing(root, "src/lib/oneteam.functions.ts", tanstackFunctionsFile(), out2, force);
+  writeIfMissing(root, "src/routes/api/oneteam/$.ts", tanstackRouteFile(), out2, force);
+  if (existsSync(join(root, "src", "start.ts")) && !force) {
+    out2.warn(
+      "found src/start.ts: not replacing it. Add a request middleware that calls oneteam.guard() so every request requires a session (see the TanStack Start example app)."
+    );
+  } else {
+    writeIfMissing(root, "src/start.ts", tanstackStartFile(), out2, force);
+  }
+}
+function validate(root, file, out2) {
+  const path = join(root, file ?? MANIFEST_FILE);
+  if (!existsSync(path)) {
+    out2.error(`${relative(root, path) || path} not found. Run \`oneteam-apps init\` first.`);
+    return { code: 1 };
+  }
+  let input;
+  try {
+    input = readJson(path);
+  } catch (error) {
+    out2.error(`${MANIFEST_FILE} is not valid JSON: ${error.message}`);
+    return { code: 1 };
+  }
+  const result = validateManifest(input);
+  if (!result.success) {
+    for (const issue of result.errors) out2.error(`${issue.path}: ${issue.message}`);
+    return { code: 1 };
+  }
+  out2.info(`${MANIFEST_FILE} is valid (scopes: ${result.manifest.scopes.join(" ")})`);
+  return { code: 0, manifest: result.manifest };
+}
+function installedVersion(root, name) {
+  try {
+    return readJson(join(root, "node_modules", name, "package.json")).version ?? null;
+  } catch {
+    return null;
+  }
+}
+function isPatchedNext(version) {
+  const [major = 0, minor = 0, patch = 0] = version.split("-")[0].split(".").map(Number);
+  if (major > 16) return true;
+  if (major === 16) return minor > 3 || minor === 3 && patch >= 8;
+  if (major === 15) return minor > 5 || minor === 5 && patch >= 28;
+  return false;
+}
+function loadEnv(root) {
+  const env = {};
+  for (const file of [".env", ".env.local"]) {
+    const path = join(root, file);
+    if (!existsSync(path)) continue;
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+      const match = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line);
+      if (match) env[match[1]] = match[2].replace(/^(['"])(.*)\1$/, "$2");
+    }
+  }
+  return env;
+}
+async function doctor(root, options, out2) {
+  let failures = 0;
+  const fail = (message) => {
+    failures += 1;
+    out2.error(message);
+  };
+  const env = { ...loadEnv(root), ...options.env };
+  const { manifest: parsed } = validate(root, void 0, out2);
+  if (!parsed) failures += 1;
+  for (const { key } of ENV_KEYS) {
+    if (!env[key]) fail(`${key} is not set (.env.local)`);
+  }
+  for (const key of Object.keys(env)) {
+    if (/^(NEXT_PUBLIC|VITE)_ONETEAM_(CLIENT_SECRET|SESSION_SECRET)/.test(key)) {
+      fail(`${key} would ship a secret to the browser. Remove the ${key.startsWith("VITE_") ? "VITE_" : "NEXT_PUBLIC_"} prefix.`);
+    }
+  }
+  if (env.ONETEAM_SESSION_SECRET && env.ONETEAM_SESSION_SECRET.length < 32) {
+    fail("ONETEAM_SESSION_SECRET must be at least 32 characters");
+  }
+  if (env.ONETEAM_APP_URL && parsed) {
+    const callback = `${env.ONETEAM_APP_URL.replace(/\/+$/, "")}/api/oneteam/callback`;
+    const registered = [...parsed.redirect_uris, ...parsed.development?.redirect_uris ?? []];
+    if (registered.includes(callback)) {
+      out2.info(`redirect URI ${callback} is in ${MANIFEST_FILE}`);
+    } else {
+      fail(`${callback} is not in ${MANIFEST_FILE} redirect_uris; Oneteam will reject the login`);
+    }
+  }
+  if (detectTanstackStartApp(root)) {
+    const start = join(root, "src", "start.ts");
+    if (!existsSync(start)) {
+      fail("no src/start.ts: requests are not protected by default. Run `oneteam-apps init`.");
+    } else if (!readFileSync(start, "utf8").includes("oneteam.guard")) {
+      fail("src/start.ts does not call oneteam.guard() from a request middleware: requests are not protected by default");
+    }
+  } else {
+    const gate = ["proxy.ts", "middleware.ts", "src/proxy.ts", "src/middleware.ts"].find(
+      (file) => existsSync(join(root, file))
+    );
+    if (!gate) {
+      fail("no proxy.ts: routes are not protected by default. Run `oneteam-apps init`.");
+    } else if (!readFileSync(join(root, gate), "utf8").includes("oneteam.proxy")) {
+      out2.warn(`${gate} does not call oneteam.proxy(); make sure it protects every route`);
+    }
+  }
+  const nextVersion = installedVersion(root, "next");
+  if (nextVersion && !isPatchedNext(nextVersion)) {
+    fail(
+      `next ${nextVersion} has known security bugs, including ones that bypass proxy.ts (and with it every Oneteam check). Upgrade to 15.5.28+ or 16.3.8+.`
+    );
+  }
+  if (!options.offline) {
+    const issuer = (env.ONETEAM_ISSUER ?? "https://login.oneteam.io").replace(/\/+$/, "");
+    try {
+      const response = await (options.fetch ?? fetch)(`${issuer}/.well-known/openid-configuration`);
+      const metadata = await response.json();
+      if (metadata.issuer === issuer) out2.info(`reached ${issuer}`);
+      else fail(`${issuer} returned issuer ${metadata.issuer}`);
+    } catch (error) {
+      fail(`could not reach ${issuer}: ${error.message}`);
+    }
+  }
+  out2.info(failures === 0 ? "All checks passed" : `${failures} problem(s) found`);
+  return failures === 0 ? 0 : 1;
+}
+
+// src/index.ts
+var HELP = `oneteam-apps: Oneteam login for your app
+
+Usage
+  oneteam-apps init [--name <app name>] [--url <production url>] [--force]
+  oneteam-apps validate [file]
+  oneteam-apps doctor [--offline]
+
+Commands
+  init      Add Oneteam login to a Next.js App Router project (non-interactive)
+  validate  Check oneteam.app.json against the manifest schema
+  doctor    Check manifest, environment, route protection and connectivity
+`;
+var out = {
+  info: (message) => console.log(message),
+  warn: (message) => console.warn(`warning: ${message}`),
+  error: (message) => console.error(`error: ${message}`)
+};
+async function main(argv) {
+  const [command, ...rest] = argv;
+  const root = process.cwd();
+  if (!command || command === "--help" || command === "-h") {
+    console.log(HELP);
+    return command ? 0 : 1;
+  }
+  if (command === "init") {
+    const { values } = parseArgs({
+      args: rest,
+      options: { name: { type: "string" }, url: { type: "string" }, force: { type: "boolean" } }
+    });
+    return init(root, values, out);
+  }
+  if (command === "validate") {
+    const { positionals } = parseArgs({ args: rest, allowPositionals: true });
+    return validate(root, positionals[0], out).code;
+  }
+  if (command === "doctor") {
+    const { values } = parseArgs({ args: rest, options: { offline: { type: "boolean" } } });
+    return doctor(root, { ...values, env: process.env }, out);
+  }
+  out.error(`unknown command "${command}"`);
+  console.log(HELP);
+  return 1;
+}
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (error) => {
+    out.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+);

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@oneteam-app/apps-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.1",
+  "description": "Set up and check Oneteam login in an app: init, validate, doctor.",
+  "keywords": [
+    "oneteam",
+    "cli",
+    "scaffold",
+    "authentication"
+  ],
+  "license": "MIT",
+  "author": "Oneteam",
+  "homepage": "https://github.com/FlexAppeal/oneteam-apps/tree/main/packages/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FlexAppeal/oneteam-apps.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/FlexAppeal/oneteam-apps/issues"
+  },
+  "type": "module",
+  "bin": {
+    "oneteam-apps": "./dist/index.js"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.9"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@oneteam-app/apps": "0.1.0-alpha.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }