@oneteam-app/apps-cli 0.1.0-alpha.5 → 0.1.0-alpha.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oneteam-app/apps-cli",
-  "version": "0.1.0-alpha.5",
-  "description": "Set up and check Oneteam login in an app: init, validate, doctor.",
+  "version": "0.1.0-alpha.7",
+  "description": "Set up, check and deploy apps for Oneteam: init, validate, doctor, login, deploy, status, logs.",
   "keywords": [
     "oneteam",
     "cli",
@@ -27,7 +27,8 @@
     "CHANGELOG.md",
     "LICENSE",
     "README.md",
-    "dist"
+    "dist",
+    "templates"
   ],
   "engines": {
     "node": ">=20.9"
@@ -37,11 +38,12 @@
     "provenance": false
   },
   "dependencies": {
-    "@oneteam-app/apps": "0.1.0-alpha.5"
+    "@oneteam-app/apps": "0.1.0-alpha.7",
+    "esbuild": "^0.28.1"
   },
   "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
+    "build": "node scripts/copy-template.mjs && tsup",
+    "test": "node scripts/copy-template.mjs && vitest run",
     "typecheck": "tsc --noEmit"
   }
 }

package/templates/hosted/.dev.vars.example

@@ -0,0 +1,11 @@
+# Local values for the secrets listed under "secrets" in oneteam.app.json.
+#
+# Copy this file to .dev.vars and fill it in yourself. .dev.vars is git-ignored
+# and never uploaded: the deployed app gets its values from a person who enters
+# them in the dashboard (the app's Secrets tab) or with
+#   npx oneteam-apps secret set NAME --env preview
+#   npx oneteam-apps secret set NAME --env live
+#
+# Use a test key here, never the live one. Names only in this file:
+#
+# SUPABASE_SERVICE_KEY=

package/templates/hosted/README.md

@@ -0,0 +1,119 @@
+# Lost and found (hosted app template)
+
+A small, complete hosted app: a React front end, an API under `/api`, and its
+own database. People are signed in before a request reaches the app, so there
+is no login code here. `oneteam-apps init --hosted <name>` copies this folder.
+
+```bash
+pnpm install
+pnpm dev        # http://localhost:5310, with a "View as" switch instead of sign-on
+pnpm test       # the permission tests
+pnpm run deploy # review, then a preview address
+```
+
+| | |
+|---|---|
+| `src/worker/index.ts` | The API (Hono). Every route has `c.get('session')`; writes check a permission with `assertCan` |
+| `src/worker/items.ts` | All database access: `env.DB` only, placeholders only, always limited to the user's communities |
+| `src/worker/index.test.ts` | Who can see and do what, with fake users |
+| `src/worker/jobs.ts` | Jobs the platform runs on a schedule. Empty to start with |
+| `src/worker/dev.ts` | Local stand-in for sign-on. Not part of what is deployed |
+| `src/client/` | The front end, built from the components of `@oneteam-app/ui`. Calls the API through `apiJson()`, never `fetch('/api/…')` |
+| `src/client/styles.css` | Two imports: Tailwind and the theme. No colours of your own |
+| `migrations/` | The database schema, applied in order |
+| `oneteam.app.json` | Name, address, what personal data is stored, who should see it, which secrets it needs |
+| `.dev.vars.example` | The names of the secrets, for whoever runs the app locally. `.dev.vars` itself is never committed |
+
+The app does not live at `/`: it is served at `/<organisation>/<app>/`, and the
+same build at `/<organisation>/<app>--preview/`. That is why Vite builds with
+`base: './'`, why `index.html` has a `<base>` tag, and why the front end uses
+`apiJson()` and `basePath()` from `@oneteam-app/apps/hosted/react`.
+
+## How it looks
+
+Screens are built from `@oneteam-app/ui` (`Page`, `List`, `Button`, `Field`, …;
+the list is in `node_modules/@oneteam-app/ui/docs/components.md`). The app is
+wrapped once in `<OneteamTheme theme={themeOf(me)}>`, which applies the
+organisation's colour and logo and follows the device's light or dark mode.
+Tailwind is the one way to style: layout classes in the markup, written for a
+phone first (`grid gap-6 md:grid-cols-2` adds the second column on a wide
+screen), and the theme's names (`bg-card`, `text-muted-foreground`) where a
+class needs a colour. There are no colours and no other `.css` files in this app.
+
+`pnpm dev` has a "Button colour" box in the bar at the top: type a hex colour to see the
+app as an organisation with that colour would. `oneteam-apps doctor` warns about
+colours written out and hand-made buttons, inputs and dialogs.
+
+## Secrets
+
+The app has its own database and needs no key for it. When it calls another
+service (Supabase, a mail provider), the key for that service is a secret: the
+code and `oneteam.app.json` only name it, and a person enters the value.
+
+1. List the name, and the host it is sent to, in `oneteam.app.json`:
+   ```json
+   "outbound_hosts": ["xyz.supabase.co"],
+   "secrets": [{ "name": "SUPABASE_SERVICE_KEY", "host": "xyz.supabase.co" }]
+   ```
+2. Add it to `Env` in `src/worker/index.ts` and read it in the Worker only:
+   ```ts
+   import { secret } from '@oneteam-app/apps/hosted';
+
+   const key = secret(c.env, 'SUPABASE_SERVICE_KEY');
+   ```
+   It throws a clear error when the value is missing. Never return the value
+   from a route, log it, or give it a `VITE_` name: everything in `src/client/`
+   is downloaded by the browser.
+3. Locally: copy `.dev.vars.example` to `.dev.vars` and fill in a test key yourself.
+4. Deployed: a person enters the value once per environment, in the dashboard
+   (the app's Secrets tab) or at a hidden prompt:
+   ```bash
+   npx oneteam-apps secret set SUPABASE_SERVICE_KEY --env preview
+   npx oneteam-apps secret set SUPABASE_SERVICE_KEY --env live
+   npx oneteam-apps secret list
+   ```
+   Preview and live each have their own value. After saving, nobody can read it
+   back, and a version cannot go live while one of its secrets has no live value.
+
+`oneteam-apps deploy` and `oneteam-apps doctor` stop when an env file is not
+git-ignored or a key is written into the code.
+
+## Scheduled jobs and sending
+
+A job is a function the platform calls on a schedule. Sending is a permission
+an admin approves. Neither needs a key, a cron service or anything outside the app.
+
+1. Say when it runs, and what the app sends, in `oneteam.app.json`:
+   ```json
+   "schedules": [{ "name": "send-reminders", "every": "day", "at": "07:00" }],
+   "sends": ["notifications"]
+   ```
+   `every` is `15_minutes`, `30_minutes`, `hour` (with `minute`), `day`, `week`
+   (with `weekdays`) or `month` (with `day_of_month`, 1 to 28). Not cron syntax.
+2. Write the handler under the same name in `src/worker/jobs.ts`:
+   ```ts
+   export const jobs = defineJobs<Env>({
+     'send-reminders': async (job, env) => {
+       const waiting = await itemsWaitingLongerThan(env.DB, 7);
+
+       await notify(job, { userIds: waiting.map((item) => item.foundBy), title: 'Still waiting', body: 'An item you logged is still here.' });
+     },
+   });
+   ```
+   Nobody is signed in during a job: there is no session, so take who it is
+   for from the app's own data. From a route, send for the person's request:
+   `await notify(c.req.raw, { … })`.
+3. Try it: `pnpm dev`, then "Run job" in the bar at the top. What the app sends
+   is printed in the terminal.
+4. `oneteam-apps deploy` checks that every schedule has a handler and the other
+   way round, and says what an admin has to approve: a new job, one that runs
+   more often, anything new under `sends`. Then:
+   ```bash
+   npx oneteam-apps job run send-reminders --env preview
+   npx oneteam-apps job list
+   ```
+
+A job has 30 seconds. A run that was missed is skipped, not caught up, and a
+run can be started by hand, so a job has to be safe to run twice. People
+outside the app's audience do not get notifications (they come back under
+`skipped`), and nobody gets more than five a day from one app.

package/templates/hosted/_gitignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+.wrangler
+*.tsbuildinfo
+
+# Local values of secrets. Never commit these: `oneteam-apps deploy` refuses to
+# run while one of them is not ignored.
+.dev.vars*
+.env*
+!.dev.vars.example
+!.env.example

package/templates/hosted/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <!-- Where the app is mounted. Locally that is the root; in production the
+         gateway replaces this with /<organisation>/<app>/. -->
+    <base href="/" />
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <meta name="theme-color" content="#ffffff" />
+    <title>Lost and found</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/client/main.tsx"></script>
+  </body>
+</html>

package/templates/hosted/migrations/0001_init.sql

@@ -0,0 +1,16 @@
+-- One row per found item. Every query filters on community_id: people only
+-- see and change items of the communities (stores) they belong to.
+CREATE TABLE items (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  community_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  location TEXT NOT NULL DEFAULT '',
+  found_by_user_id TEXT NOT NULL,
+  found_by_name TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  returned_at TEXT,
+  returned_to TEXT,
+  returned_by_user_id TEXT
+);
+
+CREATE INDEX items_by_community ON items (community_id, created_at DESC);

package/templates/hosted/oneteam.app.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://oneteam.io/schemas/app.v2.json",
+  "schema_version": 2,
+  "hosting": "hosted",
+  "name": "Lost and found",
+  "description": "Log items found in the store and mark them as returned",
+  "slug": "lost-and-found",
+  "summary": "First version: log found items, list them per store, mark them as returned.",
+  "personal_data": [
+    "Name of the employee who logged an item",
+    "Name of the person an item was returned to"
+  ],
+  "outbound_hosts": [],
+  "suggested_audience": {
+    "description": "Everyone who works in a store"
+  }
+}

package/templates/hosted/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "hosted-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler d1 migrations apply DB --local && vite dev",
+    "build": "vite build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.worker.json --noEmit",
+    "deploy": "oneteam-apps deploy"
+  },
+  "dependencies": {
+    "@oneteam-app/apps": "workspace:*",
+    "@oneteam-app/ui": "workspace:*",
+    "hono": "^4.13.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "^1.64.0",
+    "@cloudflare/vitest-plugin": "^1.7.0",
+    "@cloudflare/workers-types": "^5.20261110.1",
+    "@oneteam-app/apps-cli": "workspace:*",
+    "@tailwindcss/vite": "^4.3.5",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@vitejs/plugin-react": "^6.1.0",
+    "tailwindcss": "^4.3.5",
+    "typescript": "^5.9.0",
+    "vite": "^8.3.0",
+    "vitest": "^4.1.11",
+    "wrangler": "^4.160.0"
+  }
+}

package/templates/hosted/src/client/App.tsx

@@ -0,0 +1,276 @@
+import { apiJson, themeOf, useMe } from '@oneteam-app/apps/hosted/react';
+import {
+  ActionBar,
+  Badge,
+  Button,
+  Card,
+  EmptyState,
+  ErrorState,
+  Field,
+  List,
+  ListItem,
+  ListSkeleton,
+  OneteamTheme,
+  Page,
+  Person,
+  Section,
+  Select,
+  Tabs,
+  TextInput,
+  toast,
+} from '@oneteam-app/ui';
+import { useCallback, useEffect, useState, type FormEvent } from 'react';
+import type { Item, ItemsResponse } from '../shared';
+
+type Screen = { name: 'list' } | { name: 'add' } | { name: 'item'; item: Item } | { name: 'return'; item: Item };
+
+function formatDate(value: string): string {
+  return new Date(value).toLocaleDateString(undefined, { day: 'numeric', month: 'short' });
+}
+
+export function App() {
+  const { me, status } = useMe();
+  const [data, setData] = useState<ItemsResponse | null>(null);
+  const [screen, setScreen] = useState<Screen>({ name: 'list' });
+  const [failed, setFailed] = useState(false);
+
+  const load = useCallback(async () => {
+    try {
+      // Always through the helper: it knows the address the app is mounted at.
+      setData(await apiJson<ItemsResponse>('/api/items'));
+      setFailed(false);
+    } catch {
+      setFailed(true);
+    }
+  }, []);
+
+  useEffect(() => void load(), [load]);
+
+  const toList = () => setScreen({ name: 'list' });
+  const saved = (message: string) => {
+    toast.success(message);
+    toList();
+    void load();
+  };
+
+  return (
+    // The organisation's theme (its colours and logo), when it has set any; neutral otherwise.
+    <OneteamTheme theme={themeOf(me)}>
+      {status === 'error' || failed ? (
+        <Page title="Lost and found">
+          <ErrorState description="The items could not be loaded." onRetry={() => (status === 'error' ? location.reload() : void load())} />
+        </Page>
+      ) : screen.name === 'add' && data ? (
+        <AddItem communities={data.communities} onSaved={() => saved('Item logged')} onBack={toList} />
+      ) : screen.name === 'item' ? (
+        <ItemDetail
+          item={screen.item}
+          storeName={data?.communities.find((community) => community.id === screen.item.communityId)?.name ?? ''}
+          onReturn={() => setScreen({ name: 'return', item: screen.item })}
+          onBack={toList}
+        />
+      ) : screen.name === 'return' ? (
+        <ReturnItem item={screen.item} onSaved={() => saved('Marked as returned')} onBack={() => setScreen({ name: 'item', item: screen.item })} />
+      ) : (
+        <ItemList data={data} onAdd={() => setScreen({ name: 'add' })} onOpen={(item) => setScreen({ name: 'item', item })} />
+      )}
+    </OneteamTheme>
+  );
+}
+
+function ItemList({ data, onAdd, onOpen }: { data: ItemsResponse | null; onAdd: () => void; onOpen: (item: Item) => void }) {
+  const open = data?.items.filter((item) => !item.returnedAt) ?? [];
+  const returned = data?.items.filter((item) => item.returnedAt) ?? [];
+  const storeName = (id: string) => data?.communities.find((community) => community.id === id)?.name ?? '';
+
+  return (
+    <Page
+      title="Lost and found"
+      showBrand
+      footer={
+        // One main action per screen, where the thumb reaches it.
+        <ActionBar>
+          <Button onClick={onAdd} disabled={!data}>
+            Log a found item
+          </Button>
+        </ActionBar>
+      }
+    >
+      {!data ? (
+        <ListSkeleton />
+      ) : (
+        <Tabs
+          tabs={[
+            {
+              value: 'open',
+              label: `Waiting (${open.length})`,
+              content:
+                open.length === 0 ? (
+                  <EmptyState title="Nothing waiting to be picked up" description="Items you log show up here." />
+                ) : (
+                  <List>
+                    {open.map((item) => (
+                      <ListItem
+                        key={item.id}
+                        title={item.title}
+                        description={[item.location, storeName(item.communityId), formatDate(item.createdAt)].filter(Boolean).join(' · ')}
+                        onClick={() => onOpen(item)}
+                      />
+                    ))}
+                  </List>
+                ),
+            },
+            {
+              value: 'returned',
+              label: `Returned (${returned.length})`,
+              content:
+                returned.length === 0 ? (
+                  <EmptyState title="Nothing returned yet" />
+                ) : (
+                  <List>
+                    {returned.map((item) => (
+                      <ListItem
+                        key={item.id}
+                        title={item.title}
+                        description={`To ${item.returnedTo} · ${formatDate(item.returnedAt!)}`}
+                        trailing={<Badge tone="success">Returned</Badge>}
+                        onClick={() => onOpen(item)}
+                      />
+                    ))}
+                  </List>
+                ),
+            },
+          ]}
+        />
+      )}
+    </Page>
+  );
+}
+
+/** One item. A single column on a phone; what was found and what happened to it side by side on a wide screen. */
+function ItemDetail({ item, storeName, onReturn, onBack }: { item: Item; storeName: string; onReturn: () => void; onBack: () => void }) {
+  return (
+    <Page
+      title={item.title}
+      description={storeName}
+      back={onBack}
+      width="wide"
+      // Only for people who may hand items back; the API checks again.
+      footer={
+        item.canReturn && !item.returnedAt ? (
+          <ActionBar>
+            <Button onClick={onReturn}>Hand back</Button>
+          </ActionBar>
+        ) : undefined
+      }
+    >
+      <div className="grid gap-6 md:grid-cols-2">
+        <Section title="Found">
+          <Card>
+            <dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-2">
+              <dt className="text-muted-foreground">Where</dt>
+              <dd>{item.location || 'Not noted'}</dd>
+              <dt className="text-muted-foreground">Store</dt>
+              <dd>{storeName}</dd>
+              <dt className="text-muted-foreground">When</dt>
+              <dd>{formatDate(item.createdAt)}</dd>
+            </dl>
+          </Card>
+          <Person name={item.foundByName} detail="Logged this item" />
+        </Section>
+        <Section title="Status">
+          <Card
+            title={item.returnedAt ? <Badge tone="success">Returned</Badge> : <Badge tone="warning">Waiting to be picked up</Badge>}
+            description={item.returnedAt ? `To ${item.returnedTo} on ${formatDate(item.returnedAt)}` : 'Kept in the store until someone asks for it.'}
+          />
+        </Section>
+      </div>
+    </Page>
+  );
+}
+
+/** Sends a form once, and turns what can go wrong into words for the person who filled it in. */
+function useSubmit(send: () => Promise<unknown>, onSaved: () => void) {
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const submit = async (event: FormEvent) => {
+    event.preventDefault();
+    setBusy(true);
+    setError(null);
+
+    try {
+      await send();
+      onSaved();
+    } catch (caught) {
+      setError((caught as { status?: number }).status === 403 ? "You're not allowed to do this." : (caught as Error).message);
+      setBusy(false);
+    }
+  };
+
+  return { busy, error, submit };
+}
+
+function AddItem({ communities, onSaved, onBack }: { communities: ItemsResponse['communities']; onSaved: () => void; onBack: () => void }) {
+  const [title, setTitle] = useState('');
+  const [location, setLocation] = useState('');
+  const [communityId, setCommunityId] = useState(communities[0]?.id ?? '');
+  const { busy, error, submit } = useSubmit(
+    () => apiJson('/api/items', { method: 'POST', body: { title, location, communityId: communityId || undefined } }),
+    onSaved,
+  );
+
+  return (
+    <form onSubmit={submit}>
+      <Page
+        title="Log a found item"
+        back={onBack}
+        footer={
+          <ActionBar>
+            <Button type="submit" loading={busy}>
+              Save
+            </Button>
+          </ActionBar>
+        }
+      >
+        <Field label="What was found?" error={error} required>
+          <TextInput value={title} onChange={(event) => setTitle(event.target.value)} maxLength={120} autoFocus placeholder="Blue umbrella" />
+        </Field>
+        <Field label="Where?">
+          <TextInput value={location} onChange={(event) => setLocation(event.target.value)} maxLength={120} placeholder="Fitting rooms" />
+        </Field>
+        {communities.length > 1 && (
+          <Field label="Store">
+            <Select value={communityId} onChange={(event) => setCommunityId(event.target.value)} options={communities.map(({ id, name }) => ({ value: id, label: name }))} />
+          </Field>
+        )}
+      </Page>
+    </form>
+  );
+}
+
+function ReturnItem({ item, onSaved, onBack }: { item: Item; onSaved: () => void; onBack: () => void }) {
+  const [returnedTo, setReturnedTo] = useState('');
+  const { busy, error, submit } = useSubmit(() => apiJson(`/api/items/${item.id}/return`, { method: 'POST', body: { returnedTo } }), onSaved);
+
+  return (
+    <form onSubmit={submit}>
+      <Page
+        title="Hand back an item"
+        description={item.title}
+        back={onBack}
+        footer={
+          <ActionBar>
+            <Button type="submit" loading={busy}>
+              Mark as returned
+            </Button>
+          </ActionBar>
+        }
+      >
+        <Field label="Who picked it up?" error={error} required>
+          <TextInput value={returnedTo} onChange={(event) => setReturnedTo(event.target.value)} maxLength={120} autoFocus />
+        </Field>
+      </Page>
+    </form>
+  );
+}

package/templates/hosted/src/client/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import './styles.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/hosted/src/client/styles.css

@@ -0,0 +1,6 @@
+/* The look comes from @oneteam-app/ui: its components and its theme. The
+   organisation's own colour is applied by <OneteamTheme>. Add your own rules
+   below only for layout the components do not cover, and use the theme's
+   tokens (bg-card, text-muted-foreground, var(--primary)…), never a colour. */
+@import "tailwindcss";
+@import "@oneteam-app/ui/theme.css";

package/templates/hosted/src/shared.ts

@@ -0,0 +1,22 @@
+// Shapes the API returns and the front end reads.
+
+export interface Item {
+  id: number;
+  communityId: string;
+  title: string;
+  location: string;
+  foundByName: string;
+  createdAt: string;
+  returnedAt: string | null;
+  returnedTo: string | null;
+  /** Whether the signed-in user may mark this item as returned. The API checks again */
+  canReturn: boolean;
+}
+
+export interface ItemsResponse {
+  items: Item[];
+  communities: Array<{ id: string; name: string }>;
+}
+
+/** Who may mark an item as returned: people who manage colleagues in the item's community. */
+export const RETURN_PERMISSION = 'network::users.update';

package/templates/hosted/src/worker/dev.ts

@@ -0,0 +1,15 @@
+import { withDevSignOn } from '@oneteam-app/apps/testing';
+import manifest from '../../oneteam.app.json';
+import worker, { type Env } from './index';
+import { jobs } from './jobs';
+
+// Local development only (wrangler.jsonc points here). Stands in for the
+// sign-on gateway: every request is made as the person picked in the "View as"
+// bar at the top of the page, so the app runs without a network. The bar can
+// also run a job by hand, and what the app sends is printed in this terminal
+// instead of delivered (only what oneteam.app.json lists under "sends").
+// `oneteam-apps deploy` bundles src/worker/index.ts, which has none of this.
+export default withDevSignOn<Env>(worker, {
+  jobs,
+  sends: (manifest as { sends?: Array<'notifications' | 'chat_messages'> }).sends ?? [],
+});

package/templates/hosted/src/worker/env.d.ts

@@ -0,0 +1,10 @@
+import type { D1Migration } from '@cloudflare/vitest-plugin';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      DB: D1Database;
+      TEST_MIGRATIONS: D1Migration[];
+    }
+  }
+}