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

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,345 @@
+#!/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), tells the app who they are, and which of the\napp's own permissions they hold. Admins approve the app and assign its\npermissions to Oneteam roles.\n\n**Supported today:** Next.js App Router (Next 15.2+, 16 recommended), with\n`@oneteam-app/apps`.\n\nThe core runs on any Web-standard runtime (Node, Deno, Supabase edge functions,\nCloudflare Workers), but only the Next.js adapter ships so far. On any other\nstack, 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.** `proxy.ts` must run `oneteam.proxy()` for every route.\n  Add to `publicPaths` only what anyone on the internet may open (health\n  checks, a public landing page), and ask the user first.\n- **Never exclude routes from the proxy 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 proxy is a safety net, not the check.** Route handlers and server\n  actions still call `requirePermission` / `protectRoute` themselves.\n- **Check permissions on the server, every time.** Every server action and\n  route handler that reads or changes protected data 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('expenses.approve', { communityId: expense.communityId })`.\n  Scope list queries with `oneteam.communitiesFor(session, key)`.\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_`, never log tokens or sessions,\n  never pass `getAccessToken()` results to client components.\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- **Community-level permissions are not organisation-wide.**\n  `can(session, key)` without `communityId` is only true for organisation-level\n  grants. That's intended: don't \"fix\" it by dropping the community check.\n\n## The shape of a protected app\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// any server action or route handler that touches protected data\nconst expense = await db.expense.findUniqueOrThrow({ where: { id } });\nawait oneteam.requirePermission('expenses.approve', { 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.** `package.json` has `next` and 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 `*.vercel.app` preview URL as the production domain.\n   `init` creates `lib/oneteam.ts`, `app/api/oneteam/[...oneteam]/route.ts`,\n   `proxy.ts`, `oneteam.app.json` and `.env.example` entries. It won't overwrite\n   an existing `middleware.ts`/`proxy.ts`: merge `oneteam.proxy()` into it yourself.\n3. **Declare what the app needs** in `oneteam.app.json`:\n   - `scopes`: add `oneteam:organisation` for the employee number,\n     `oneteam:communities` / `oneteam:functions` for memberships. Request only\n     what the app uses; admins see and approve each one.\n   - `permissions`: one entry per action that not every employee may do, e.g.\n     `{ \"key\": \"expenses.approve\", \"name\": \"Approve expenses\", \"levels\": [\"organisation\", \"community\"] }`.\n     Use `community` level when the action belongs to a store/location/team.\n   - Run `npx @oneteam-app/apps-cli validate`.\n4. **Protect the app** following [references/nextjs.md](references/nextjs.md)\n   and the rules above.\n5. **Hand over registration to the user.** Registration happens in the Oneteam\n   dashboard by an admin: Settings \u2192 Apps & Shortcuts \u2192 Apps \u2192 New app, upload\n   `oneteam.app.json`. They get a client id and secret. Tell the user to put\n   them in `.env.local` (and in the hosting provider's environment settings)\n   themselves. Never ask the user to paste secrets into the chat.\n6. **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- Confirming an admin assigned the app's permissions to 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/nextjs.md](references/nextjs.md): API and patterns for the Next.js adapter\n- [references/checklist.md](references/checklist.md): final security review\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.** `proxy.ts` must run `oneteam.proxy()` for every route.\n  Add to `publicPaths` only what anyone on the internet may open (health\n  checks, a public landing page), and ask the user first.\n- **Never exclude routes from the proxy 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 proxy is a safety net, not the check.** Route handlers and server\n  actions still call `requirePermission` / `protectRoute` themselves.\n- **Check permissions on the server, every time.** Every server action and\n  route handler that reads or changes protected data 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('expenses.approve', { communityId: expense.communityId })`.\n  Scope list queries with `oneteam.communitiesFor(session, key)`.\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_`, never log tokens or sessions,\n  never pass `getAccessToken()` results to client components.\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- **Community-level permissions are not organisation-wide.**\n  `can(session, key)` without `communityId` is only true for organisation-level\n  grants. That's intended: don't \"fix\" it by dropping the community check.\n\n## The shape of a protected app\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// any server action or route handler that touches protected data\nconst expense = await db.expense.findUniqueOrThrow({ where: { id } });\nawait oneteam.requirePermission('expenses.approve', { 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_" },
+  { 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`],
+    scopes: ["openid", "profile", "email", "offline_access"],
+    permissions: [],
+    development: {
+      login_uri: "http://localhost:3000/api/oneteam/login",
+      redirect_uris: ["http://localhost:3000/api/oneteam/callback"]
+    }
+  };
+}
+
+// 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;
+}
+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 next = detectNextApp(root);
+  if (!next) {
+    out2.error(
+      'No Next.js App Router project found (needs "next" in package.json and an app/ or src/app/ directory). Other frameworks: use @oneteam-app/apps directly, see the README.'
+    );
+    return 1;
+  }
+  const force = options.force ?? false;
+  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);
+  }
+  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: Settings \u2192 Apps & Shortcuts \u2192 Apps \u2192 New app (upload ${MANIFEST_FILE})`);
+  out2.info("  3. Put the client id and secret in .env.local, plus ONETEAM_SESSION_SECRET");
+  out2.info("  4. npx oneteam-apps doctor");
+  return 0;
+}
+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 (${result.manifest.permissions.length} permissions)`);
+  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_ONETEAM_(CLIENT_SECRET|SESSION_SECRET)/.test(key)) {
+      fail(`${key} would ship a secret to the browser. Remove the 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`);
+    }
+  }
+  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,46 @@
 {
   "name": "@oneteam-app/apps-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.0",
+  "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": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.9"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@oneteam-app/apps": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }