wirl 0.2.2 → 0.2.3

package/bin.js

@@ -2977,6 +2977,9 @@ function parseManifest(input) {
     }
     accent = rawAccent;
   }
+  const rawVisibility = raw["visibility"];
+  if (rawVisibility !== void 0 && rawVisibility !== "private") return refuse(VISIBILITY_REFUSED);
+  const visibility = rawVisibility === "private" ? { visibility: "private" } : {};
   const flowResult = parseFlows(raw);
   if (!flowResult.ok) return refuse(flowResult.message);
   const flows = flowResult.flows;
@@ -2995,7 +2998,7 @@ function parseManifest(input) {
     if (!publicPathsResult2.ok) return refuse(publicPathsResult2.message);
     return {
       ok: true,
-      manifest: { runtime, connections: [], description, accent, schedules, flows, publicPaths: publicPathsResult2.publicPaths, static: staticFiles, migrations },
+      manifest: { runtime, connections: [], description, accent, schedules, flows, publicPaths: publicPathsResult2.publicPaths, static: staticFiles, migrations, ...visibility },
       warnings
     };
   }
@@ -3054,11 +3057,11 @@ function parseManifest(input) {
   if (!publicPathsResult.ok) return refuse(publicPathsResult.message);
   return {
     ok: true,
-    manifest: { runtime, connections, description, accent, schedules, flows, publicPaths: publicPathsResult.publicPaths, static: staticFiles, migrations },
+    manifest: { runtime, connections, description, accent, schedules, flows, publicPaths: publicPathsResult.publicPaths, static: staticFiles, migrations, ...visibility },
     warnings
   };
 }
-var CONNECTION_KINDS, UNDELIVERED_KINDS, CREATABLE_CONNECTION_KINDS, needsNoKey, ACCENTS, SCHEDULE_LIMITS, MANIFEST_KEYS, QUIET_KEYS, UNKNOWN_KEYS_NAMED, KEY_SHOWN, squash, ONE_EDIT_MIN_LETTERS, pluralOf, SLUG, LABEL, HOST_PATTERN, refuse, asHint, SCHEDULE_NAME, TIMEOUT_PATTERN, TIMEOUT_MESSAGE, FLOW_KEYS, MIGRATIONS_KEYS;
+var CONNECTION_KINDS, UNDELIVERED_KINDS, CREATABLE_CONNECTION_KINDS, needsNoKey, ACCENTS, SCHEDULE_LIMITS, MANIFEST_KEYS, QUIET_KEYS, UNKNOWN_KEYS_NAMED, KEY_SHOWN, squash, ONE_EDIT_MIN_LETTERS, pluralOf, SLUG, LABEL, HOST_PATTERN, refuse, asHint, SCHEDULE_NAME, TIMEOUT_PATTERN, TIMEOUT_MESSAGE, FLOW_KEYS, MIGRATIONS_KEYS, VISIBILITY_REFUSED;
 var init_manifest = __esm({
   "packages/core/src/manifest.ts"() {
     "use strict";
@@ -3098,7 +3101,8 @@ var init_manifest = __esm({
       "server",
       "spa",
       "start",
-      "static"
+      "static",
+      "visibility"
     ]);
     QUIET_KEYS = Object.freeze(["$schema"]);
     UNKNOWN_KEYS_NAMED = 10;
@@ -3120,6 +3124,7 @@ var init_manifest = __esm({
     TIMEOUT_MESSAGE = (name) => `timeout for ${name} must be between 30s and 15m; a run longer than that should be split into resumable chunks.`;
     FLOW_KEYS = ["name", "step_timeout", "retries"];
     MIGRATIONS_KEYS = ["destructive"];
+    VISIBILITY_REFUSED = `visibility can only be "private": it sets who can open a new app when a deploy creates it. Change an existing app's visibility with wirl visibility.`;
   }
 });
 
@@ -4713,7 +4718,7 @@ var init_version = __esm({
   "packages/core/src/version.ts"() {
     "use strict";
     WORKSPACE_VERSION = "0.0.0";
-    BUILT_VERSION = true ? "0.2.2" : null;
+    BUILT_VERSION = true ? "0.2.3" : null;
   }
 });
 
@@ -4767,6 +4772,22 @@ var init_connect = __esm({
   }
 });
 
+// packages/core/src/setup-prompt.ts
+function starterName(email) {
+  const handle = (email ?? "").split("@")[0] ?? "";
+  const slug = handle.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  const cut2 = slug.slice(0, SLUG_MAX - STARTER_SUFFIX.length).replace(/-+$/, "");
+  return cut2 === "" ? "starter" : `${cut2}${STARTER_SUFFIX}`;
+}
+var STARTER_SUFFIX;
+var init_setup_prompt = __esm({
+  "packages/core/src/setup-prompt.ts"() {
+    "use strict";
+    init_slug();
+    STARTER_SUFFIX = "-starter";
+  }
+});
+
 // packages/core/src/porting.ts
 function dependencyNames(packageJson) {
   if (packageJson === void 0) return [];
@@ -5119,6 +5140,7 @@ var init_src = __esm({
     init_install();
     init_share_role();
     init_connect();
+    init_setup_prompt();
     init_porting();
     init_throttle_report();
     init_supplied_bundle();
@@ -7291,6 +7313,429 @@ ${FLOWS_CONTRACT}
 `;
 }
 
+// packages/cli/src/starter.ts
+init_src();
+var STARTER_CONFLICT = "Choose one: --server or --starter.";
+var SUGGESTIONS = [
+  {
+    title: "Rename it to something we'd actually use",
+    prompt: `Rename this noticeboard to something my team would actually use. Ask me what we would use it for, suggest three names, and when I pick one, change the page's title and heading and the description in wirl.json to match. Keep "app" in wirl.json as it is: a new name there would make a second app at a new address. Then deploy it with wirl deploy.`
+  },
+  {
+    title: "Try a new look in a preview first",
+    prompt: "Give the noticeboard a warmer look: pinned notes as coloured cards, and tags as small coloured labels. Put it up with wirl preview first and give me the preview's address to check. Deploy it with wirl deploy only after I say it looks right."
+  },
+  {
+    title: "Add a due date to notes",
+    prompt: "Add an optional due date to notes on the noticeboard. Add the column in a new file, migrations/0002_due_date.sql, and never edit 0001. Let people set the date when they post or edit a note, show it on each note, and put notes due soonest at the top. Try it with wirl dev, then deploy it with wirl deploy."
+  },
+  {
+    title: "Show the weather from a public API",
+    prompt: `Show today's weather for our office at the top of the noticeboard, from Open-Meteo, a public weather API that needs no key. Ask me which city our office is in. Add this entry to "connections" in wirl.json: {"slug": "open-meteo", "kind": "none", "hosts": ["api.open-meteo.com"]}. Fetch Open-Meteo's own URL from server.mjs, and deploy it with wirl deploy. If the deploy says open-meteo is waiting, the connection needs approving, which your sign-in cannot do: tell me to approve it on the app's Connections page on app.wirl.dev, or to ask an admin of our organisation to. The weather shows once it is approved.`
+  },
+  {
+    title: "Change when the tidy-up runs",
+    prompt: "Change the noticeboard's nightly tidy-up: archive notes after 14 days instead of 30, and run it at 6pm on weekdays in my time zone (ask me which). Change the schedule in wirl.json and the number in server.mjs, deploy it with wirl deploy, then run it once with wirl run tidy and tell me what it said."
+  },
+  {
+    title: "Find out what happened from the logs",
+    prompt: "Read this app's logs with wirl logs and tell me, in a few lines, what people did on the noticeboard today and whether anything failed."
+  },
+  {
+    title: "Share it with a colleague",
+    prompt: `Help me share this noticeboard with a colleague. Sharing is done by me, not by a deploy: tell me to share it from the app's Access page on app.wirl.dev (the "Who can open it" row on the noticeboard links to it), where I add their email address. Then tell me what they will see when they open the address.`
+  }
+];
+var SUGGESTIONS_SOURCE = [
+  "const SUGGESTIONS = [",
+  ...SUGGESTIONS.map(({ title, prompt }) => `  { title: ${JSON.stringify(title)}, prompt: ${JSON.stringify(prompt)} },`),
+  "];"
+].join("\n");
+var SERVER_HEAD = String.raw`/**
+ * Team noticeboard: your first app on wirl.
+ *
+ * Your team posts short notes here, tags them, pins the ones everyone should
+ * see, and edits or removes their own. Every night a schedule archives old
+ * notes nobody pinned. The page also explains itself: a "How this works on
+ * wirl" panel, one row per feature, each linking to that page of the app on
+ * app.wirl.dev, and a few changes to ask your coding agent for next.
+ *
+ * The whole app is this one file:
+ * - The page is HTML this module returns: plain forms, no script.
+ * - Notes live in env.DB, a SQLite database that belongs to this app alone.
+ *   Its tables are in migrations/0001_init.sql, and wirl applies each new
+ *   file in migrations/ before a version goes live. Put the next change in
+ *   migrations/0002_<what>.sql rather than editing that one.
+ * - Who is asking arrives in headers wirl sets after signing them in, which
+ *   the browser cannot forge. Who may change a note is a line of code here:
+ *   a check in the page is only a suggestion to whoever holds the browser.
+ * - The nightly schedule is declared in wirl.json. wirl sends it here as a
+ *   POST to /__wirl/schedule/tidy, and what it answers becomes the run's note.
+ * - console.log lines appear on the app's Logs page, and in wirl logs.
+ */
+
+const TITLE = "Team noticeboard";
+const DASHBOARD = "https://app.wirl.dev";
+const ARCHIVE_AFTER_DAYS = 30;
+const LONGEST_NOTE = 2000;
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    // One line per request, on the Logs page.
+    console.log(request.method, url.pathname);
+
+    // The nightly tidy-up, sent by wirl at the time wirl.json gives. wirl
+    // names the schedule in x-wirl-schedule as well as in the path, and a
+    // request without that header is not one wirl sent.
+    if (url.pathname.startsWith("/__wirl/schedule/")) {
+      const name = url.pathname.slice("/__wirl/schedule/".length);
+      const fromWirl = request.headers.get("x-wirl-schedule") === name;
+      if (name === "tidy" && request.method === "POST" && fromWirl) return tidy(env);
+      return text("No such schedule", 404);
+    }
+
+    const me = visitor(request);
+
+    if (request.method === "POST") {
+      // A form posted from another site is never one of yours.
+      if (request.headers.get("sec-fetch-site") === "cross-site") return text("Refused: this form came from another site.", 403);
+      if (me.id === "") return text("Sign in to change the board.", 403);
+      let form;
+      try {
+        form = await request.formData();
+      } catch {
+        return text("Send this as a form.", 400);
+      }
+      return change(url.pathname, form, me, env);
+    }
+
+    if (url.pathname === "/" && (request.method === "GET" || request.method === "HEAD")) {
+      return html(await page(request, url, me, env));
+    }
+    return text("Not found", 404);
+  },
+};
+
+// Set by wirl after it signed this person in. Never take identity from a form
+// or the query string: those say whatever the browser wants them to say. A
+// header carries only Latin-1 and a name can be anything, so wirl
+// percent-encodes the name; it is decoded here.
+function visitor(request) {
+  const header = (name) => decode(request.headers.get(name) || "");
+  return {
+    id: header("x-wirl-user-id"),
+    name: header("x-wirl-user-name") || header("x-wirl-user-email") || "someone",
+    role: header("x-wirl-role"),
+  };
+}
+
+// POST /notes, and POST /notes/<id>/<edit|pin|remove|restore>.
+async function change(path, form, me, env) {
+  const [, first, id, action] = path.split("/");
+  if (first !== "notes") return text("Not found", 404);
+
+  if (id === undefined) {
+    const body = clean(form.get("body"), LONGEST_NOTE);
+    if (body === "") return text("A note needs some words.", 400);
+    const { meta } = await env.DB.prepare("insert into notes (body, tags, author_id, author_name) values (?, ?, ?, ?)")
+      .bind(body, tags(form.get("tags")), me.id, me.name)
+      .run();
+    console.log("note", meta.last_row_id, "posted by", me.id);
+    return home();
+  }
+
+  const number = Number.parseInt(id, 10);
+  if (String(number) !== id) return text("Not found", 404);
+  const note = await env.DB.prepare("select id, author_id from notes where id = ?").bind(number).first();
+  if (!note) return text("No such note", 404);
+
+  // The rule that matters, in code: authors change their own notes, and the
+  // app's owner can change any. Anyone on the board can pin.
+  const mine = note.author_id === me.id || me.role === "owner";
+
+  if (action === "pin") {
+    await env.DB.prepare("update notes set pinned = 1 - pinned where id = ?").bind(number).run();
+    console.log("note", number, "pin changed by", me.id);
+    return home();
+  }
+  if (!mine) return text("Only the person who posted this note, or the app's owner, can change it.", 403);
+
+  if (action === "edit") {
+    const body = clean(form.get("body"), LONGEST_NOTE);
+    if (body === "") return text("A note needs some words.", 400);
+    await env.DB.prepare("update notes set body = ?, tags = ? where id = ?").bind(body, tags(form.get("tags")), number).run();
+    console.log("note", number, "edited by", me.id);
+    return home();
+  }
+  if (action === "remove") {
+    await env.DB.prepare("delete from notes where id = ?").bind(number).run();
+    console.log("note", number, "removed by", me.id);
+    return home();
+  }
+  if (action === "restore") {
+    // Back on the board as if posted today, so tonight's tidy-up leaves it be.
+    await env.DB.prepare("update notes set archived_at = null, created_at = datetime('now') where id = ?").bind(number).run();
+    console.log("note", number, "put back by", me.id);
+    return home("/?view=archived");
+  }
+  return text("Not found", 404);
+}
+
+// The schedule: archive notes older than ARCHIVE_AFTER_DAYS that nobody
+// pinned, and keep a line saying so, which the page shows as the last run.
+async function tidy(env) {
+  const { meta } = await env.DB.prepare(
+    "update notes set archived_at = datetime('now') where archived_at is null and pinned = 0 and created_at < datetime('now', ?)",
+  )
+    .bind("-" + ARCHIVE_AFTER_DAYS + " days")
+    .run();
+  const note = "Archived " + meta.changes + (meta.changes === 1 ? " note" : " notes") + " older than " + ARCHIVE_AFTER_DAYS + " days.";
+  await env.DB.prepare("insert into runs (schedule, note) values (?, ?)").bind("tidy", note).run();
+  console.log("tidy:", note);
+  return text(note);
+}
+
+async function page(request, url, me, env) {
+  const tag = tags(url.searchParams.get("tag")).split(",")[0];
+  const archived = url.searchParams.get("view") === "archived";
+  let sql = "select id, body, tags, pinned, author_id, author_name, created_at from notes where archived_at is " + (archived ? "not null" : "null");
+  const binds = [];
+  if (tag !== "") {
+    sql += " and (',' || tags || ',') like ?";
+    binds.push("%," + tag + ",%");
+  }
+  sql += " order by pinned desc, id desc limit 200";
+  const notes = (await env.DB.prepare(sql).bind(...binds).all()).results;
+  const archivedCount = await env.DB.prepare("select count(*) as n from notes where archived_at is not null").first("n");
+  const lastRun = await env.DB.prepare("select note, ran_at from runs where schedule = 'tidy' order by id desc limit 1").first();
+
+  const shown = archived
+    ? "<p class='dim'>Notes the nightly tidy-up moved off the board. <a href='/'>Back to the board</a></p>"
+    : form() +
+      "<p class='dim filters'>" +
+      (tag === "" ? "All notes" : "Tagged <b>" + escape(tag) + "</b> · <a href='/'>show all</a>") +
+      " · <a href='/?view=archived'>Archived (" + archivedCount + ")</a></p>";
+
+  return [
+    "<!doctype html>",
+    "<html lang='en'>",
+    "<meta charset='utf-8'>",
+    "<meta name='viewport' content='width=device-width, initial-scale=1'>",
+    "<title>" + TITLE + "</title>",
+    "<style>" + STYLE + "</style>",
+    "<main>",
+    "<header><h1>" + TITLE + "</h1>",
+    "<p class='dim'>Your first app on wirl. Signed in as <b>" + escape(me.name) + "</b>" + (me.role ? " (" + escape(me.role) + ")" : "") + ".</p></header>",
+    shown,
+    "<ul class='notes'>" + (notes.length === 0 ? "<li class='dim'>Nothing here yet.</li>" : notes.map((note) => card(note, me, archived)).join("")) + "</ul>",
+    panel(request, me, lastRun),
+    suggestions(),
+    "</main>",
+    "</html>",
+  ].join("\n");
+}
+
+function form() {
+  return [
+    "<form class='add' method='post' action='/notes'>",
+    "<textarea name='body' rows='3' maxlength='" + LONGEST_NOTE + "' required placeholder='Post a note for the team'></textarea>",
+    "<input name='tags' placeholder='Tags, separated by commas'>",
+    "<button class='primary'>Post</button>",
+    "</form>",
+  ].join("");
+}
+
+function card(note, me, archived) {
+  const mine = note.author_id === me.id || me.role === "owner";
+  const action = (what, label) =>
+    "<form method='post' action='/notes/" + note.id + "/" + what + "'><button>" + label + "</button></form>";
+  const tagLinks = note.tags
+    .split(",")
+    .filter((tag) => tag !== "")
+    .map((tag) => "<a class='tag' href='/?tag=" + encodeURIComponent(tag) + "'>#" + escape(tag) + "</a>")
+    .join(" ");
+  const controls = archived
+    ? (mine ? action("restore", "Put back") : "")
+    : action("pin", note.pinned ? "Unpin" : "Pin") +
+      (mine
+        ? "<details><summary>Edit</summary><form class='edit' method='post' action='/notes/" + note.id + "/edit'>" +
+          "<textarea name='body' rows='3' maxlength='" + LONGEST_NOTE + "' required>" + escape(note.body) + "</textarea>" +
+          "<input name='tags' value='" + escape(note.tags.split(",").join(", ")) + "'>" +
+          "<button class='primary'>Save</button></form></details>" +
+          action("remove", "Remove")
+        : "");
+  return (
+    "<li class='note" + (note.pinned && !archived ? " pinned" : "") + "'>" +
+    "<p>" + escape(note.body) + "</p>" +
+    "<div class='meta dim'>" + (note.pinned && !archived ? "<b>Pinned</b> · " : "") +
+    escape(note.author_name || "someone") + " · " + escape(note.created_at.slice(0, 10)) + (tagLinks ? " · " + tagLinks : "") + "</div>" +
+    "<div class='actions'>" + controls + "</div>" +
+    "</li>"
+  );
+}
+
+// The app's page on the dashboard, from the address it was opened at:
+// <org>--<app>.wirl.run, or <org>--<app>--<preview>.wirl.run for a preview.
+// Under wirl dev the address is 127.0.0.1, which names no app: null.
+function dashboard(request) {
+  const label = new URL(request.url).hostname.split(".")[0];
+  const parts = label.split("--");
+  if (parts.length < 2) return null;
+  const org = request.headers.get("x-wirl-org") || parts[0];
+  return DASHBOARD + "/apps/" + encodeURIComponent(org) + "/" + encodeURIComponent(parts[1]);
+}
+
+function panel(request, me, lastRun) {
+  const base = dashboard(request);
+  const last = lastRun ? "Last run " + lastRun.ran_at.slice(0, 16) + " UTC: " + lastRun.note : "Not run yet.";
+  // One row per feature: what it is, what it does in this app, and its page.
+  const rows = [
+    ["Who can open it", "wirl signed you in before this page loaded and tells the app who you are, in headers: here you are " + me.name + (me.role ? ", " + me.role : "") + ". The app has no sign-in code of its own. It started private to you; choose who else can open it on Access.", "/access", "Access"],
+    ["Your data", "Notes are rows in this app's own SQLite database. Its tables are in migrations/0001_init.sql, and a deploy applies each new file in migrations/ before it goes live.", "/deployments", "Deployments"],
+    ["A schedule", "tidy runs every night at 02:00 UTC and archives notes older than " + ARCHIVE_AFTER_DAYS + " days that nobody pinned. " + last + " Run it now from Overview.", "", "Overview"],
+    ["Logs", "Each request writes a line with console.log, and so does each change to a note. Read them on Logs, or ask your agent to run wirl logs.", "/logs", "Logs"],
+    ["Versions", "Each wirl deploy is a new version, and the earlier ones stay: going back to one takes a click.", "/deployments", "Deployments"],
+    ["Previews", "wirl preview puts a change up at an address of its own, with its own database, and nothing goes live until you deploy. Open previews are listed on Overview.", "", "Overview"],
+    ["Outside APIs", "Declare a connection in wirl.json and fetch the service's own URL: wirl adds the key on the way out, so it never reaches this code or a chat.", "/connections", "Connections"],
+    ["Settings", "Describe the app for your team's list of tools, hand it to someone else, or delete it.", "/settings", "Settings"],
+  ];
+  return [
+    "<section><h2>How this works on wirl</h2>",
+    "<table>",
+    ...rows.map(([feature, what, path, label]) =>
+      "<tr><td>" + feature + "</td><td>" + escape(what) + "</td><td>" +
+      (base === null ? "<span class='dim'>" + label + "</span>" : "<a href='" + escape(base + path) + "'>" + label + "</a>") +
+      "</td></tr>",
+    ),
+    "</table>",
+    base === null ? "<p class='dim'>Running under wirl dev, so these pages are not linked here: they open on app.wirl.dev once it is deployed.</p>" : "",
+    "</section>",
+  ].join("\n");
+}
+
+function suggestions() {
+  return [
+    "<section><h2>Ask your agent for a first change</h2>",
+    "<p class='dim'>Each of these is a whole prompt. Open one, copy it, and paste it to the coding agent that made this app.</p>",
+    ...SUGGESTIONS.map((each) => "<details><summary>" + escape(each.title) + "</summary><pre>" + escape(each.prompt) + "</pre></details>"),
+    "</section>",
+  ].join("\n");
+}
+
+`;
+var SERVER_TAIL = String.raw`
+
+const STYLE = [
+  ":root { color-scheme: light dark; --ink: #1d1d1b; --dim: #66655f; --line: #e2e0d9; --card: #ffffff; --bg: #f7f6f2; --pin: #fff3bf; --accent: #2b6b5a; }",
+  "@media (prefers-color-scheme: dark) { :root { --ink: #ecebe6; --dim: #a6a59f; --line: #36352f; --card: #1f1f1c; --bg: #161614; --pin: #3b3420; --accent: #8fd1bd; } }",
+  "body { margin: 0; background: var(--bg); color: var(--ink); font: 15px/1.5 system-ui, sans-serif; }",
+  "main { max-width: 760px; margin: 0 auto; padding: 24px 16px 48px; }",
+  "h1 { font-size: 24px; margin: 0 0 4px; } h2 { font-size: 17px; margin: 36px 0 8px; }",
+  "a { color: var(--accent); } .dim { color: var(--dim); }",
+  "form.add, form.edit { display: grid; gap: 8px; margin: 16px 0 8px; }",
+  "textarea, input, button { font: inherit; color: inherit; padding: 7px 10px; border: 1px solid var(--line); border-radius: 6px; background: var(--card); }",
+  "button { cursor: pointer; } button.primary { justify-self: start; background: var(--accent); border-color: var(--accent); color: var(--bg); }",
+  "ul.notes { list-style: none; padding: 0; display: grid; gap: 10px; }",
+  ".note { background: var(--card); border: 1px solid var(--line); border-radius: 8px; padding: 12px 14px; }",
+  ".note.pinned { background: var(--pin); }",
+  ".note p { margin: 0 0 6px; white-space: pre-wrap; overflow-wrap: anywhere; }",
+  ".meta, .actions { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; font-size: 13px; }",
+  ".actions { margin-top: 8px; } .actions form { margin: 0; } .actions details { flex-basis: 100%; order: 3; }",
+  ".tag { text-decoration: none; }",
+  "table { width: 100%; border-collapse: collapse; font-size: 14px; }",
+  "td { border-top: 1px solid var(--line); padding: 8px 6px; vertical-align: top; }",
+  "td:first-child { font-weight: 600; }",
+  "pre { white-space: pre-wrap; background: var(--card); border: 1px solid var(--line); border-radius: 6px; padding: 10px; font-size: 13px; }",
+  "details { margin: 6px 0; } summary { cursor: pointer; }",
+].join("\n");
+
+const home = (to = "/") => new Response(null, { status: 303, headers: { location: to } });
+
+const text = (body, status = 200) => new Response(body, { status, headers: { "content-type": "text/plain; charset=utf-8" } });
+
+const html = (markup) => new Response(markup, { headers: { "content-type": "text/html; charset=utf-8" } });
+
+// Escapes text for HTML, in content and in quoted attribute values alike.
+const escape = (value) =>
+  String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+
+const decode = (value) => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+
+// A form field as trimmed text, at most max characters.
+const clean = (value, max) => (typeof value === "string" ? value.trim().slice(0, max) : "");
+
+// "Team, Stand-up" becomes "team,stand-up": lowercase words, letters, digits
+// and hyphens only, so a tag is safe in a link and in the LIKE above.
+const tags = (value) =>
+  clean(value, 200)
+    .split(",")
+    .map((tag) => tag.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((word) => word !== "").join("-"))
+    .filter((tag, i, all) => tag !== "" && all.indexOf(tag) === i)
+    .slice(0, 8)
+    .join(",");
+`;
+var SERVER_MODULE = `${SERVER_HEAD}${SUGGESTIONS_SOURCE}${SERVER_TAIL}`;
+var STARTER_MIGRATION = [
+  "-- The noticeboard's tables. wirl applies each new file here, in order, before a version goes live.",
+  "-- Make the next change in 0002_<what>.sql; never edit a file that has been deployed.",
+  "create table notes (id integer primary key, body text not null, tags text not null default '', pinned integer not null default 0, author_id text not null, author_name text not null default '', created_at text not null default (datetime('now')), archived_at text)",
+  "create table runs (id integer primary key, schedule text not null, note text not null, ran_at text not null default (datetime('now')))",
+  "insert into notes (body, tags, pinned, author_id, author_name) values ('Welcome to the noticeboard. Post a note below, tag it, and pin the ones everyone should see.', 'welcome', 1, '', 'wirl')",
+  ""
+].join("\n");
+function starterManifest(app, org) {
+  const manifest = {
+    app,
+    ...org ? { org } : {},
+    dir: ".",
+    server: "server.mjs",
+    description: "A team noticeboard: your first app on wirl",
+    visibility: "private",
+    schedules: [{ name: "tidy", cron: "0 2 * * *", timezone: "UTC" }]
+  };
+  return `${JSON.stringify(manifest, null, 2)}
+`;
+}
+var README = [
+  "# Team noticeboard",
+  "",
+  "Your first app on wirl: a board where your team posts short notes, tags them, pins the ones everyone should see, and edits or removes their own. Every night a schedule archives old notes nobody pinned.",
+  "",
+  'Open it at the address `wirl deploy` prints. It starts private to you. Its page has a "How this works on wirl" panel: one row per thing wirl does for this app, each linking to that page of the app on app.wirl.dev.',
+  "",
+  "## What is where",
+  "",
+  "- `server.mjs`: the whole app, one module with one `fetch`. The page, the forms, who may change a note, and the nightly tidy-up.",
+  "- `migrations/0001_init.sql`: the tables, one statement a line. Put the next change in `migrations/0002_<what>.sql`.",
+  "- `wirl.json`: the app's name, its module, its nightly schedule, and that it is created private.",
+  "- `.claude/skills/wirl/SKILL.md`: how a coding agent works with wirl.",
+  "",
+  "## Run it on this computer",
+  "",
+  `    ${WIRL_BIN} dev`,
+  "",
+  "It prints the address to open, and a `curl` line that runs the nightly tidy-up now.",
+  "",
+  "## Changes to ask your agent for",
+  "",
+  "Each is a whole prompt: paste it to your coding agent as it is.",
+  "",
+  ...SUGGESTIONS.flatMap(({ title, prompt }) => [`### ${title}`, "", `> ${prompt}`, ""])
+].join("\n");
+var STARTER_FILES = {
+  "server.mjs": SERVER_MODULE,
+  "migrations/0001_init.sql": STARTER_MIGRATION,
+  "README.md": README,
+  "wirl.json": starterManifest("starter")
+};
+
 // packages/cli/src/core.ts
 function credentialsPath(env = process.env) {
   return env["WIRL_CREDENTIALS_PATH"] || join5(homedir(), ".config", "wirl", "credentials.json");
@@ -7633,23 +8078,23 @@ var INIT_MIGRATION = [
   ""
 ].join("\n");
 var INIT_MIGRATION_PATH = `${MIGRATIONS_DIR}/${ADOPTED_FILE}`;
-async function refuseInitMigrations(dir) {
+async function refuseInitMigrations(dir, flag) {
   for (const entry of await readdir(dir, { withFileTypes: true })) {
     if (entry.name.toLowerCase() !== MIGRATIONS_DIR) continue;
     if (entry.isSymbolicLink()) {
-      throw new CliError(`${entry.name}/ is a symbolic link, and wirl writes into no links: make migrations/ a real folder, then run wirl init --server again.`);
+      throw new CliError(`${entry.name}/ is a symbolic link, and wirl writes into no links: make migrations/ a real folder, then run wirl init ${flag} again.`);
     }
     if (entry.name !== MIGRATIONS_DIR) {
-      throw new CliError(`${entry.name}/ is spelled differently from migrations/: wirl reads migrations/ in lowercase only. Rename it, then run wirl init --server again.`);
+      throw new CliError(`${entry.name}/ is spelled differently from migrations/: wirl reads migrations/ in lowercase only. Rename it, then run wirl init ${flag} again.`);
     }
     if (!entry.isDirectory()) {
       throw new CliError(
-        `migrations is a file, and wirl init --server writes ${INIT_MIGRATION_PATH} into a folder of that name. Move it aside, then run wirl init --server again.`
+        `migrations is a file, and wirl init ${flag} writes ${INIT_MIGRATION_PATH} into a folder of that name. Move it aside, then run wirl init ${flag} again.`
       );
     }
     const names = await readdir(join5(dir, entry.name));
     if (names.some((name) => name.toLowerCase().endsWith(".sql"))) {
-      throw new CliError(`migrations/ already holds .sql files; wirl init --server writes ${INIT_MIGRATION_PATH} into a folder with none.`);
+      throw new CliError(`migrations/ already holds .sql files; wirl init ${flag} writes ${INIT_MIGRATION_PATH} into a folder with none.`);
     }
   }
 }
@@ -7694,23 +8139,52 @@ async function pulledDevCommand(dir) {
   }
   return `${needsInstall ? "npm install && " : ""}${WIRL_BIN} dev`;
 }
+function starterFile(path) {
+  const text = STARTER_FILES[path];
+  if (text === void 0) throw new Error(`starter.ts has no ${path}`);
+  return text;
+}
+function moduleKit(options) {
+  if (options.starter) {
+    return {
+      flag: "--starter",
+      files: ["server.mjs", INIT_MIGRATION_PATH, "README.md"].map((path) => [path, starterFile(path)]),
+      hint: "Run wirl init --starter in a new folder, or move the existing file."
+    };
+  }
+  if (options.server) {
+    return {
+      flag: "--server",
+      files: [
+        ["server.mjs", SERVER_TEMPLATE],
+        [INIT_MIGRATION_PATH, INIT_MIGRATION]
+      ],
+      hint: "Remove --server, or move the existing file."
+    };
+  }
+  return null;
+}
 async function scaffold(dir, options) {
+  if (options.server && options.starter) throw new CliError(STARTER_CONFLICT);
+  const kit = moduleKit(options);
   const written = [];
   await mkdir3(dir, { recursive: true });
-  if (options.server) {
-    const target = join5(dir, "server.mjs");
-    try {
-      await readFile3(target);
-      throw new CliError(`server.mjs already exists in ${dir}.`, "Remove --server, or move the existing file.");
-    } catch (error) {
-      if (error instanceof CliError) throw error;
-    }
-    await refuseInitMigrations(dir);
-    await writeFile2(target, SERVER_TEMPLATE, "utf8");
-    written.push("server.mjs");
-    await mkdir3(join5(dir, MIGRATIONS_DIR), { recursive: true });
-    await writeFile2(join5(dir, MIGRATIONS_DIR, ADOPTED_FILE), INIT_MIGRATION, { encoding: "utf8", flag: "wx" });
-    written.push(INIT_MIGRATION_PATH);
+  if (kit !== null) {
+    for (const [name] of kit.files) {
+      if (name === INIT_MIGRATION_PATH) continue;
+      try {
+        await readFile3(join5(dir, name));
+        throw new CliError(`${name} already exists in ${dir}.`, kit.hint);
+      } catch (error) {
+        if (error instanceof CliError) throw error;
+      }
+    }
+    await refuseInitMigrations(dir, kit.flag);
+    for (const [name, text] of kit.files) {
+      await mkdir3(dirname3(join5(dir, name)), { recursive: true });
+      await writeFile2(join5(dir, name), text, { encoding: "utf8", flag: "wx" });
+      written.push(name);
+    }
     const pkg = join5(dir, "package.json");
     if (await readFile3(pkg, "utf8").catch(() => null) === null) {
       await writeFile2(pkg, `${JSON.stringify({ name: options.app, private: true, type: "module" }, null, 2)}
@@ -7724,8 +8198,9 @@ async function scaffold(dir, options) {
     dir: ".",
     ...options.server ? { server: "server.mjs" } : {}
   };
-  await writeFile2(join5(dir, MANIFEST_NAME), `${JSON.stringify(manifest, null, 2)}
-`, "utf8");
+  const manifestText = kit?.flag === "--starter" ? starterManifest(options.app, options.org) : `${JSON.stringify(manifest, null, 2)}
+`;
+  await writeFile2(join5(dir, MANIFEST_NAME), manifestText, "utf8");
   const gitignore = join5(dir, ".gitignore");
   const existing = await readFile3(gitignore, "utf8").catch(() => "");
   const wanted = [".wirl/", ".env"].filter((line) => !existing.split("\n").includes(line));
@@ -7994,7 +8469,7 @@ async function callApi(creds, path, options = {}) {
     const body = parsed ?? {};
     const refusal = apiRefusal(parsed, response);
     if (response.status === 403 && body.error === "insufficient_scope" && body.message) {
-      throw new CliError(body.message, "Ask the person to do it in the dashboard, or reconnect with full access.", refusal);
+      throw new CliError(body.message, `Ask the person to do it in the dashboard, or run ${WIRL_BIN} login and tick full access on the approval page.`, refusal);
     }
     if (response.status === 403 && (body.error === "person_only" || body.error === "bad_confirmation") && body.message) {
       throw new CliError(body.message, void 0, refusal);
@@ -8195,6 +8670,11 @@ function manifestWarningLines(manifest) {
   const parsed = parseManifest(manifest);
   return parsed.ok ? parsed.warnings.map((warning) => `Warning: ${warning}`) : [];
 }
+function manifestVisibility(manifest) {
+  if (manifest === null || manifest === void 0) return void 0;
+  const parsed = parseManifest(manifest);
+  return parsed.ok ? parsed.manifest.visibility : void 0;
+}
 async function prepareDeployBundle(dir, manifest, door, projectDir) {
   let server;
   let rules = NO_MANIFEST;
@@ -8401,6 +8881,10 @@ function formatOrgLine(org) {
   return org.domain ? `${head}  ${org.domain}: new apps start visible to everyone in it` : `${head}  no company domain: new apps start private`;
 }
 var whoami = (creds) => callApi(creds, "/api/v1/me");
+function signedInSentence(me) {
+  const gave = (me.scope ?? "full") === "full" ? "full access" : "build-and-update";
+  return `Signed in (${gave}). Organisations: ${me.orgs.map((o) => o.slug).join(", ") || "none yet"}.`;
+}
 function chooseOrg(orgs, given, hint = 'Pass --org <slug>, or add "org" to wirl.json.') {
   const named = (given ?? "").trim();
   if (named) return named;
@@ -8414,13 +8898,25 @@ async function resolveAppsOrg(creds, orgFlag, manifestOrg) {
   return chooseOrg((await whoami(creds)).orgs, null);
 }
 var listApps = (creds, org) => callApi(creds, `/api/v1/orgs/${seg(org)}/apps`);
-var createRemoteApp = (creds, org, slug, name) => callApi(creds, `/api/v1/orgs/${seg(org)}/apps`, {
+var createRemoteApp = (creds, org, slug, name, visibility) => callApi(creds, `/api/v1/orgs/${seg(org)}/apps`, {
   method: "POST",
-  body: JSON.stringify({ slug, name: name ?? slug }),
+  // `visibility` rides along only when wirl.json said it: absent, the
+  // org's default holds. It applies to the app this create makes and to
+  // no other: an app that exists answers 409 and is left as it is.
+  body: JSON.stringify({ slug, name: name ?? slug, ...visibility === void 0 ? {} : { visibility } }),
   contentType: "application/json"
 });
-async function ensureRemoteApp(creds, org, app) {
-  return createRemoteApp(creds, org, app).then(() => true, (error) => {
+async function ensureRemoteApp(creds, org, app, visibility) {
+  return createRemoteApp(creds, org, app, void 0, visibility).then((created) => {
+    const made = created.app?.visibility;
+    if (visibility === "private" && typeof made === "string" && made !== "private") {
+      process.stderr.write(
+        `${terminalSafe(`wirl: asked for a private app, but ${org}/${app} was created visible to everyone in the organisation (an older control plane, or someone created it first). Change it with: wirl visibility private --org ${org} --app ${app}`)}
+`
+      );
+    }
+    return true;
+  }, (error) => {
     if (!(error instanceof CliError)) throw error;
     if (error.fields["code"] === "app_deleted") throw deletedNameError(error, app);
     if (error.fields["code"] === "app_exists" || error.fields["code"] === "app_moved") throw takenNameError(error, app);
@@ -8466,7 +8962,7 @@ function deletedAppMessage(org, app, done) {
   return `Deleted ${org}/${app}. Its address has stopped answering${runs}. Its data is kept until ${done.dataKeptUntil.slice(0, 10)}; until then wirl apps restore ${app} --org ${org} brings it back (one that was public comes back only from the Recently deleted list on the dashboard). Its name stays taken.`;
 }
 function deleteNeedsFullScopeMessage(apiOrigin, org, app) {
-  return `This sign-in can deploy, but not delete an app: deleting one needs a full-scope sign-in. Sign in with ${WIRL_BIN} login (with WIRL_TOKEN unset), or delete it on its Settings page: ${apiOrigin}/apps/${seg(org)}/${seg(app)}/settings`;
+  return `This sign-in can deploy, but not delete an app: deleting one needs a full-scope sign-in. Sign in with ${WIRL_BIN} login (with WIRL_TOKEN unset) and tick full access on the approval page, or delete it on its Settings page: ${apiOrigin}/apps/${seg(org)}/${seg(app)}/settings`;
 }
 var VISIBILITY_LEVELS = ["private", "org", "public"];
 function describeVisibility(level, org) {
@@ -9973,6 +10469,7 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "no-skill",
   "print",
   "server",
+  "starter",
   "force",
   "errors",
   "follow",
@@ -9994,7 +10491,7 @@ function commandFlags(listed2, everywhere = true) {
 }
 var COMMAND_FLAGS = /* @__PURE__ */ new Map([
   ["login", commandFlags({ values: ["token", "api"] })],
-  ["init", commandFlags({ booleans: ["server", "no-skill"] })],
+  ["init", commandFlags({ booleans: ["server", "starter", "no-skill"] })],
   ["skill", commandFlags({ booleans: ["print"] })],
   // Only what it lists, as DEV_FLAGS in bin.ts does (OIM-887): `--json` and `--app` were always refused here.
   ["dev", commandFlags({ values: ["user", "name", "role", "org", "port"], booleans: ["verbose"] }, false)],
@@ -10988,6 +11485,7 @@ var USAGE = `wirl \u2014 deploy an app somewhere real, behind a sign-in
 
   wirl login                    Sign in from this terminal (or --token wirl_...)
   wirl init [dir] [--server]    Create wirl.json, and a working server module with --server
+  wirl init [dir] --starter     Write your first app: a small team noticeboard, ready to deploy
   wirl skill [dir] [--print]    Write the skill file a coding agent reads (init does this too; --no-skill to skip)
   wirl dev [dir]                Run the app here, signed in as a stub user
   wirl deploy [dir]             Build, scan and deploy (creates the app if new)
@@ -11051,14 +11549,18 @@ var HELP = {
     example: "wirl login"
   },
   init: {
-    usage: ["wirl init [dir] [--server] [--app <name>] [--org <slug>] [--no-skill]"],
+    usage: ["wirl init [dir] [--server|--starter] [--app <name>] [--org <slug>] [--no-skill]"],
     flags: [
       { flag: "--app <name>", desc: "App slug. Defaults to the directory name." },
       { flag: "--org <slug>", desc: "Organisation to put in wirl.json." },
       { flag: "--server", desc: "Also write server.mjs, a working backend to build on." },
+      {
+        flag: "--starter",
+        desc: "Write your first app instead: a team noticeboard that shows what wirl does, private to you when deployed. Without [dir], the folder is <your-name>-starter."
+      },
       { flag: "--no-skill", desc: "Skip writing the skill file a coding agent reads." }
     ],
-    example: "wirl init my-app --server"
+    example: "wirl init --starter\n  wirl init my-app --server"
   },
   skill: {
     usage: ["wirl skill [dir] [--print]"],
@@ -11502,6 +12004,13 @@ async function resolveTarget(creds, args2, dir) {
   return { org: String(org), app };
 }
 var args = parseArgs(process.argv.slice(2).map((token) => token === "-h" ? "--help" : token));
+async function starterFolder() {
+  const creds = await loadCredentials().catch(() => null);
+  if (creds === null) return starterName(null);
+  const me = await whoami(creds).catch(() => null);
+  if (me === null) err("Could not read your account, so the starter is named starter.");
+  return starterName(me?.email ?? null);
+}
 async function main() {
   const json2 = args.flags.has("json");
   if (process.argv[2] === "--version" || process.argv[2] === "-v") {
@@ -11542,23 +12051,28 @@ async function main() {
     const creds2 = await pollDeviceLogin(apiOrigin, login);
     const path = await saveCredentials(creds2);
     const me = await whoami(creds2);
-    out(`Signed in. Organisations: ${me.orgs.map((o) => o.slug).join(", ") || "none yet"}.`);
+    out(signedInSentence(me));
     out(`Saved to ${path}`);
     return 0;
   }
   if (args.command === "init") {
     refuseBadFlags(args);
     refuseExtraPositionals("init", args.positional, 1, "one folder", { hint: folderHint("The app's name goes after --app <name>.") });
-    const dir = resolve6(args.positional[0] ?? ".");
+    const starter = args.flags.has("starter");
+    if (starter && args.flags.has("server")) throw new CliError(STARTER_CONFLICT);
+    const dir = resolve6(args.positional[0] ?? (starter ? await starterFolder() : "."));
     const app = String(args.flags.get("app") ?? basename4(dir));
     const written = await scaffold(dir, {
       app,
       ...args.flags.has("org") ? { org: String(args.flags.get("org")) } : {},
       server: args.flags.has("server"),
+      starter,
       skill: !args.flags.has("no-skill")
     });
     for (const file of written) out(`Wrote ${file}`);
     if (args.flags.has("server")) out("Deploy it with: wirl deploy");
+    const folder = relative3(process.cwd(), dir);
+    if (starter) out(`Deploy it with: ${folder === "" ? "" : `cd ${shellPath(folder)} && `}wirl deploy`);
     return 0;
   }
   if (args.command === "skill") {
@@ -11664,7 +12178,7 @@ async function main() {
       const upload = { dir, projectDir: project.manifestDir, org: target.org, app: target.app, ...manifest === null ? {} : { manifest } };
       const prepared = await prepareUpload(dir, upload.manifest, "wirl deploy", upload.projectDir);
       for (const line of prepared.notices) err(line);
-      const made = !args.flags.has("no-create") && await ensureRemoteApp(creds, target.org, target.app);
+      const made = !args.flags.has("no-create") && await ensureRemoteApp(creds, target.org, target.app, manifestVisibility(manifest));
       const terminal = terminalMayConfirm({ stdinIsTTY: process.stdin.isTTY, stdoutIsTTY: process.stdout.isTTY, stderrIsTTY: process.stderr.isTTY, json: json2 }) ? personAt(process.stdin, process.stderr) : void 0;
       const result = await deploy(creds, { ...upload, prepared, ...terminal === void 0 ? {} : { terminal } }).catch((error) => {
         throw withMadeApp(error, made, "wirl deploy", target.app);
@@ -11725,7 +12239,7 @@ async function main() {
       const upload = { dir, projectDir: project.manifestDir, org: target.org, app: target.app, name: resolved, ...manifest === null ? {} : { manifest } };
       const prepared = await prepareUpload(dir, upload.manifest, "wirl preview", upload.projectDir);
       for (const line of prepared.notices) err(line);
-      const made = !args.flags.has("no-create") && await ensureRemoteApp(creds, target.org, target.app);
+      const made = !args.flags.has("no-create") && await ensureRemoteApp(creds, target.org, target.app, manifestVisibility(manifest));
       const result = await deployPreview(creds, { ...upload, prepared }).catch((error) => {
         throw withMadeApp(error, made, "wirl preview", target.app);
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wirl",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Deploy an internal app somewhere real, privately. One command; sharing by email; API keys declared, never pasted.",
   "keywords": [
     "deploy",