@tiniestcloud/create 0.0.0-stage → 0.1.6

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @tiniestcloud/create
 
-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.
+Start an app or a website for [Tiniest Cloud](https://tiniest.cloud), which gives it sign-in,
+storage and AI with no backend to write.
+
+```sh
+npm create @tiniestcloud@latest my-app                    # an app
+npm create @tiniestcloud@latest my-site -- --template site # a website
+```
+
+- **app**: React, TypeScript, Vite, Tailwind CSS and shadcn/ui, for something people sign in
+  to and use. The SDK, its TypeScript types and React hooks are already wired in.
+- **site**: Astro and Tailwind CSS, for pages people read. Every file in `src/pages` is a page.
+
+Both come with the `tiny-design` skill in `.agents/skills` and `.claude/skills`, so Claude Code,
+Codex, Cursor, Gemini CLI, GitHub Copilot and other coding agents pick up how it should look
+without installing anything.
+
+Then:
+
+```sh
+cd my-app
+npm install
+npm run build
+```
+
+and deploy the `dist` folder to Tiniest Cloud, from the dashboard or your coding agent.

package/index.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * npm create @tiniestcloud@latest <folder> [-- --template app|site]
+ *
+ * Copies a starter project for Tiniest Cloud into a new folder: 'app' is React, TypeScript,
+ * Vite, Tailwind CSS and shadcn/ui with the platform's SDK wired in; 'site' is Astro and
+ * Tailwind CSS. The templates are the same files the platform's get_starter tool returns.
+ * Beside them goes the tiny-design skill, so any coding agent opened in the project finds the
+ * design guidance without anyone installing it.
+ *
+ * No dependencies and no prompts: it is run by coding agents as often as by people, and an
+ * agent cannot answer a question on a terminal.
+ */
+import { cp, mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+const TEMPLATES = {
+  app: "React, TypeScript, Vite, Tailwind CSS and shadcn/ui",
+  site: "Astro and Tailwind CSS",
+};
+// The SDK's types, always the ones the platform serves today. The copy bundled at publish time
+// is only for when that address cannot be reached.
+const TYPES_URL = process.env.TINIEST_CLOUD_TYPES_URL ?? "https://app.tiniest.cloud/sdk.d.ts";
+// Where coding agents look for a project's skills without being told: .agents/skills is read
+// by Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and most others, .claude/skills by
+// Claude Code. The skill is copied into the package when it is published (prepack).
+const SKILL = join(import.meta.dirname, "skills", "tiny-design");
+const SKILL_DIRS = [".agents/skills", ".claude/skills"];
+
+const USAGE = `Usage: npm create @tiniestcloud@latest <folder> -- --template <app|site>
+
+  app   ${TEMPLATES.app} — something people sign in to and use
+  site  ${TEMPLATES.site} — pages people read`;
+
+function fail(message) {
+  console.error(`${message}\n\n${USAGE}`);
+  process.exit(1);
+}
+
+let args;
+try {
+  args = parseArgs({
+    allowPositionals: true,
+    options: {
+      template: { type: "string", short: "t" },
+      app: { type: "boolean" },
+      site: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+} catch (err) {
+  fail(err.message);
+}
+if (args.values.help) {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+const kind = args.values.template ?? (args.values.site ? "site" : "app");
+if (!(kind in TEMPLATES)) fail(`"${kind}" is not a template.`);
+if (args.positionals.length > 1) fail(`One folder at a time; got ${args.positionals.join(", ")}.`);
+
+const folder = args.positionals[0] ?? (kind === "site" ? "my-site" : "my-app");
+const target = resolve(folder);
+if (existsSync(target) && (await readdir(target)).length > 0) {
+  fail(`${folder} already exists and is not empty. Choose a new folder.`);
+}
+
+async function sdkTypes() {
+  try {
+    const res = await fetch(TYPES_URL, { signal: AbortSignal.timeout(10_000) });
+    if (res.ok) return await res.text();
+  } catch {
+    // Falls through to the bundled copy.
+  }
+  const bundled = join(import.meta.dirname, "sdk.d.ts");
+  if (existsSync(bundled)) {
+    console.warn(`Could not reach ${TYPES_URL}; using the SDK types bundled with this package.`);
+    return await readFile(bundled, "utf8");
+  }
+  return null;
+}
+
+// Fetched before anything is written, so a failure leaves no half-made folder behind.
+const types = kind === "app" ? await sdkTypes() : null;
+if (kind === "app" && types === null) {
+  console.error(`Could not download the SDK's types from ${TYPES_URL}. Check the connection and run this again.`);
+  process.exit(1);
+}
+
+await mkdir(target, { recursive: true });
+await cp(join(import.meta.dirname, "templates", kind), target, { recursive: true });
+// Stored without its dot: npm leaves a .gitignore out of a published package.
+await rename(join(target, "gitignore"), join(target, ".gitignore"));
+if (types !== null) await writeFile(join(target, "src", "tiny.d.ts"), types);
+if (existsSync(SKILL)) {
+  for (const dir of SKILL_DIRS) await cp(SKILL, join(target, dir, "tiny-design"), { recursive: true });
+}
+
+const pkgPath = join(target, "package.json");
+const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+pkg.name = basename(target).toLowerCase().replace(/[^a-z0-9-~._]+/g, "-").replace(/^[-._]+/, "") || pkg.name;
+await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+
+console.log(`Created ${folder}: ${TEMPLATES[kind]}.
+
+  cd ${folder}
+  npm install
+  npm run build
+
+Then deploy the dist folder to Tiniest Cloud.${
+  kind === "app"
+    ? "\n`npm run dev` shows a notice instead of the app: sign-in and data come from Tiniest Cloud, so it runs once deployed."
+    : ""
+}`);

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@tiniestcloud/create",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.6",
+  "description": "Start an app or website for Tiniest Cloud: React, TypeScript, Vite, Tailwind CSS and shadcn/ui, or Astro.",
+  "keywords": [
+    "tiniest-cloud",
+    "create",
+    "starter",
+    "react",
+    "vite",
+    "astro",
+    "shadcn"
+  ],
+  "homepage": "https://tiniest.cloud",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-tiniest-cloud": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "sdk.d.ts",
+    "skills",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "scripts": {
+    "prepack": "cp ../server/public/sdk.d.ts sdk.d.ts && rm -rf skills && mkdir skills && cp -R ../../skills/tiny-design skills/tiny-design"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/sdk.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Types for the Tiniest Cloud SDK — the global `tiny` that `<script src="/sdk.js"></script>`
+ * defines. Drop this file into a TypeScript project (src/tiny.d.ts) and `tiny` is typed
+ * everywhere, with nothing to import or install.
+ *
+ * Served at /sdk.d.ts. Always the types for the SDK this deployment serves; a test fails
+ * when sdk.js gains a method this file does not declare.
+ */
+
+declare namespace Tiny {
+  /** Errors the SDK throws. `status` is the HTTP status, or 0 when the platform was unreachable. */
+  interface TinyError extends Error {
+    name: "TinyError";
+    status: number;
+  }
+
+  interface User {
+    id: string;
+    email: string;
+  }
+
+  interface Entry<T = unknown> {
+    key: string;
+    value: T;
+    /** ISO timestamp of the last write. */
+    updated_at: string;
+    /** ISO timestamp of the first write. Kept by the platform; a page cannot set it. */
+    created_at: string;
+    /**
+     * Who created it, as an id that is the same for one person across this app's entries — not
+     * their account id, and different in every other app. Use it to group or filter entries by
+     * person (`where: { $created_by: entry.created_by }`); use `mine` for "is it yours". Kept by
+     * the platform. Null when no person did: a job, a webhook, an app key, a visitor with no
+     * account.
+     */
+    created_by: string | null;
+    /** Whether the signed-in person reading it created it. */
+    mine: boolean;
+  }
+
+  /** A range bound: a number compares numbers, a Date or ISO date string compares times, other text compares text. */
+  type Bound = number | string | Date;
+
+  type Comparison = {
+    eq?: unknown;
+    ne?: unknown;
+    gt?: Bound;
+    gte?: Bound;
+    lt?: Bound;
+    lte?: Bound;
+    /** Equal to any of these, compared as text. */
+    in?: Array<string | number | boolean>;
+    /** Contains this text, ignoring case. */
+    contains?: string;
+  };
+
+  /**
+   * A filter applied on the server, eight conditions at most. Keys are top-level fields of the
+   * stored value, or the entry's own `$created_at`, `$updated_at` (ranges) and `$created_by`
+   * ("me", or an entry's `created_by`). A bare value means equals (compared as text, so 5 matches "5"); an array
+   * means one of them.
+   */
+  type Where = Record<string, string | number | boolean | null | Date | Array<string | number | boolean> | Comparison>;
+
+  interface Filter {
+    where?: Where;
+  }
+
+  interface Ordered {
+    /**
+     * A field of the value to sort by — numbers as numbers, text in byte order, entries without
+     * it last — or `$created_at`, `$updated_at`, `$key`. A leading `-` is newest or largest first.
+     * Ties break on the key. Default: key order.
+     */
+    order?: string;
+  }
+
+  interface Page<T = unknown> {
+    prefix: string;
+    count: number;
+    entries: Entry<T>[];
+    /** Pass back for the next page; null at the end. */
+    cursor: string | null;
+  }
+
+  interface Group {
+    value: string | null;
+    count: number;
+    /** Present when `sum` was asked for. */
+    sum?: number;
+    avg?: number;
+    min?: number;
+    max?: number;
+    counted?: number;
+  }
+
+  interface WatchOptions extends Filter, Ordered {
+    /** With `order`, only the first N — "the latest 50 messages". */
+    limit?: number;
+    /** Called when the live connection cannot be made or is refused. */
+    onError?: (error: TinyError) => void;
+  }
+
+  interface DB {
+    /** The stored value, or null when there is none. */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Any JSON value up to 256 KB. Resolves to the value stored. */
+    set<T>(key: string, value: T): Promise<T>;
+    /** Save only if the key is new — atomic; a racing second caller rejects with status 409. */
+    create<T>(key: string, value: T): Promise<T>;
+    /** Whether something was deleted. */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Entries under a prefix. With `limit`, the first N (up to 1,000) in `order`; without it,
+     * every match, and an error past 1,000 rather than part of them.
+     */
+    list<T = unknown>(prefix?: string, options?: Filter & Ordered & { limit?: number }): Promise<Entry<T>[]>;
+    page<T = unknown>(prefix?: string, options?: Filter & Ordered & { cursor?: string | null; limit?: number }): Promise<Page<T>>;
+    /** Every entry under a prefix, paging automatically. A forward pass, not a snapshot. */
+    scan<T = unknown>(prefix?: string, options?: Filter & Ordered & { limit?: number }): AsyncIterable<Entry<T>>;
+    /** Live: calls back with the current entries on connect and after every change. Returns stop. */
+    watch<T = unknown>(prefix: string, onChange: (entries: Entry<T>[]) => void, options?: WatchOptions): () => void;
+    count(prefix?: string, options?: Filter): Promise<number>;
+    sum(prefix: string, field: string, options?: Filter): Promise<number>;
+    sumDetail(prefix: string, field: string, options?: Filter): Promise<{ prefix: string; field: string; sum: number; counted: number }>;
+    /** { value: count } per distinct value of `by`. Errors past 100 groups. */
+    countBy(prefix: string, by: string, options?: Filter): Promise<Record<string, number>>;
+    /** { value: total of field } per distinct value of `by`. */
+    sumBy(prefix: string, field: string, by: string, options?: Filter): Promise<Record<string, number>>;
+    /** `bucket` groups by the first N characters of `by` — 7 is per month for ISO dates. */
+    groupBy(prefix: string, options: Filter & { by?: string; sum?: string; bucket?: number }): Promise<Group[]>;
+  }
+
+  interface RoomMessage {
+    /** The sending connection — not a person; the same someone in two tabs is two senders. */
+    from: string;
+    data: string;
+  }
+
+  interface Room {
+    /** This connection, as others see it. Null until connected. */
+    readonly id: string | null;
+    /** Strings go as-is; anything else is JSON-encoded. Up to 4 KB. */
+    send(data: unknown): void;
+    /** Returns a function that removes the handler. */
+    on(handler: (message: RoomMessage) => void): () => void;
+    leave(): void;
+  }
+
+  type Effort = "low" | "medium" | "high" | "xhigh" | "max";
+
+  /** A File or Blob, what files.put returned (or its id or url), or a data: URL. */
+  type ImageInput = Blob | StoredFile | string;
+
+  interface GenerateOptions {
+    system?: string;
+    model?: string;
+    effort?: Effort;
+    /** Up to four. */
+    images?: ImageInput[];
+  }
+
+  type Question =
+    | { type: "noul"; instructions: string }
+    | { type: "choice"; instructions: string; criteria: Record<string, string> }
+    | { type: "score"; instructions: string; criteria: string[] };
+
+  type Answer<Q extends Question> = Q extends { type: "noul" }
+    ? { type: "noul"; noul: number }
+    : Q extends { type: "choice"; criteria: Record<infer K extends string, string> }
+      ? { type: "choice"; choice: K; confidence: number; probabilities: Record<K, number> }
+      : { type: "score"; score: number; confidence: number; probabilities: Record<string, number> };
+
+  interface Limits {
+    models: string[];
+    max_effort: Effort;
+    default_effort: Effort;
+    remaining: { user_hour: number; app_day: number };
+    judge: { available: boolean; remaining: { user_hour: number; app_day: number } };
+  }
+
+  interface AI {
+    generate(prompt: string, options?: GenerateOptions): Promise<string>;
+    stream(prompt: string, options?: GenerateOptions): AsyncIterable<string>;
+    /** Typed decisions about a text, answered as values to branch on. */
+    judge<Q extends Record<string, Question>>(state: unknown, questions: Q): Promise<{ [K in keyof Q]: Answer<Q[K]> }>;
+    limits(): Promise<Limits>;
+  }
+
+  interface StoredFile {
+    id: string;
+    url: string;
+    name: string;
+    type: string;
+    size: number;
+  }
+
+  interface Files {
+    put(file: Blob, options?: { name?: string; onProgress?: (percent: number) => void }): Promise<StoredFile>;
+    /** Where the bytes are, for an <img src>. */
+    url(ref: StoredFile | string): string;
+    delete(ref: StoredFile | string): Promise<boolean>;
+  }
+
+  interface FetchOptions {
+    /** "/..." or "?..."; the host is the connection's. */
+    path?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean>;
+    body?: string;
+    /** Any value, sent as application/json. */
+    json?: unknown;
+  }
+
+  interface FetchResult<T = any> {
+    ok: boolean;
+    status: number;
+    headers: Record<string, string>;
+    text: string;
+    /** Parsed when the response is JSON, else null. */
+    json: T | null;
+  }
+
+  interface Notify {
+    supported(): Promise<boolean>;
+    enabled(): Promise<boolean>;
+    /** Must run from a tap. Resolves true when the person said yes. */
+    ask(): Promise<boolean>;
+    stop(): Promise<void>;
+    test(): Promise<{ sent: number; pruned: number; skipped: number; failed: number }>;
+    /** Moves a subscribed device onto the server's current key. The SDK runs it on load. */
+    refresh(): Promise<void>;
+  }
+
+  /**
+   * What a backend function receives as its second argument — the platform, from the server
+   * side: `export default async (input, tiny: Tiny.Server) => value`. Reads and writes reach
+   * the caller's data under the app's rules, with the `function` role added.
+   */
+  interface Server {
+    /** Who called, or null for a visitor with no account. */
+    caller: { id: string; email: string; roles: string[] } | null;
+    db: ServerDB;
+    fetch<T = any>(connection: string, options?: FetchOptions): Promise<FetchResult<T>>;
+    ai: ServerAI;
+  }
+
+  interface ServerDB {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<T>;
+    /** Save only if the key is new — atomic; a racing second call throws with status 409. */
+    create<T>(key: string, value: T): Promise<T>;
+    delete(key: string): Promise<boolean>;
+    list<T = unknown>(prefix?: string, options?: Filter): Promise<Entry<T>[]>;
+    page<T = unknown>(prefix?: string, options?: Filter & { cursor?: string | null; limit?: number }): Promise<Page<T>>;
+    count(prefix?: string, options?: Filter): Promise<number>;
+    sum(prefix: string, field: string, options?: Filter): Promise<number>;
+    groupBy(prefix: string, options: Filter & { by?: string; sum?: string; bucket?: number }): Promise<Group[]>;
+  }
+
+  interface ServerAI {
+    generate(prompt: string, options?: Omit<GenerateOptions, "images">): Promise<string>;
+    judge<Q extends Record<string, Question>>(state: unknown, questions: Q): Promise<{ [K in keyof Q]: Answer<Q[K]> }>;
+  }
+
+  interface SDK {
+    /** The signed-in visitor, or null. */
+    me(): Promise<User | null>;
+    /** Send the visitor to sign in, returning to this page afterwards. */
+    login(): void;
+    logout(): Promise<void>;
+    db: DB;
+    room(name: string): Room;
+    ai: AI;
+    files: Files;
+    /** Run one of the app's backend functions (`_functions/<name>.js`) and get what it returned. */
+    call<T = any>(name: string, input?: unknown): Promise<T>;
+    /** Call an API through a connection the app's owner set up. */
+    fetch<T = any>(connection: string, options?: FetchOptions): Promise<FetchResult<T>>;
+    notify: Notify;
+  }
+}
+
+/** Defined by <script src="/sdk.js"></script>; absent anywhere the app is not served by Tiniest Cloud. */
+declare var tiny: Tiny.SDK;
+
+interface Window {
+  tiny: Tiny.SDK;
+}