fb0b837 · 7480030 · 9a6110a · c92e089 · 6dc3f45 · 2727297
@@ -713,6 +713,74 @@
is resting and why, with a button to use it again sooner. Nothing granted
anywhere means the forge's own token, as before. Every run remembers the
account it spent.
### Prompts from Instagram
A repository's next tell can come from its audience. Under Settings →
Prompts an admin connects the Instagram account of the app — a game with
an account of its own, say — and once a day the forge reads the account's
latest Reel, takes its most-liked top-level comment, and tells the crew
exactly as a person would from the studio box: an issue is opened and
routed to a builder. The comment is the tell; the forge invents nothing.
What happens at the hour, every day, in UTC:
1. The token is refreshed when it is more than fifty days old (below).
2. The account's username is read once, the first time, and shown.
3. The latest Reel is found — the newest item Instagram marks `REELS`, or
   the newest video where it marks nothing.
4. Its top-level comments are read, at most four pages of fifty. The top
   comment is the one with the most likes; a tie goes to the earliest. A
   comment with no text does not count.
5. The crew is told, and the Reel is remembered as told.
The tell has one shape. Its first line is the issue's title, as with any
tell, and the rest is its body:
```
<the comment, as written>
From Instagram: the top comment (<n> likes) by @<username> on the Reel of <YYYY-MM-DD>. <permalink>
```
Nothing is told twice, and nothing is told early. A Reel already told is
skipped ("No new Reel since <date>; the last one was told as #<n>."), a
Reel with no comments yet is left for tomorrow and _not_ remembered as told
("The latest Reel has no comments yet."), and an account with no Reel says
so ("No Reel yet."). Every run leaves its sentence on the settings page, and
**Fetch now** runs the same routine at once, whatever the hour. A run that
meets an error ends in a sentence too, never a throw: Instagram's own words
in one line, or — for a token Instagram no longer accepts — "connect the
account again". A repository whose routine ran today does not run again
until tomorrow, and one whose forge was down at the hour catches up on the
next tick.
The token is a long-lived Instagram user token, which lives sixty days. It
is sealed under the forge's key, bound to its row, opened only for the run,
and never listed or shown again; the API's listing carries the account, the
hour, and what the last run said, and nothing else. When it is more than
fifty days old the forge refreshes it — Instagram allows a refresh once a
token is a day old — stores the new one sealed, and notes the time, so a
token pasted once stays good for as long as the account does. A token the
forge cannot open (a data directory restored under another key) asks to be
connected again, like everything else about a lost key.
The one-time steps at Meta, none of which needs App Review for an account
of your own:
1. Make the Instagram account a professional one (Business or Creator).
2. At developers.facebook.com, make a Meta app and add the **Instagram**
   product with Business Login for Instagram. No Facebook Page is needed.
3. Get a token for the account with the scopes `instagram_business_basic`
   and `instagram_business_manage_comments`.
4. Exchange it for a long-lived token, the one that lives sixty days.
5. Paste it under Settings → Prompts, choose the hour, and press Add — or
   `POST /api/v1/repos/:owner/:name/prompts` with
   `{ "kind": "instagram", "token": "…", "at": "15:00" }`.
`prompt.told` on the outbox names the source, the Reel, the comment and the
issue; it is for the repository's admins, like everything else about its
settings.
## Configuration
| variable                  | default                         | meaning                                           |
@@ -0,0 +1,152 @@
/**
 * Prompt-source actions: connect the Instagram account whose Reels prompt
 * the crew, look at it now, and disconnect it. Admin over the repository,
 * like every other setting that spends the crew's time. The daily run
 * itself is the routine's (`crew/prompts.ts`); `Fetch now` borrows it.
 */
import type { App } from "../app.ts";
import {
  addPromptSource as insertSource,
  getPromptSource,
  listPromptSources as querySources,
  removePromptSource as deleteSource,
  type AddPromptError,
  type PromptKind,
  type PromptSource,
} from "../core/prompts.ts";
import type { Repo } from "../core/repos.ts";
import type { User } from "../core/users.ts";
import { promptsFor } from "../crew/prompts.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { requireRepoAdmin } from "./access.ts";
/** A source as a page or the API shows it: everything but the token. */
export interface PromptSourceView {
  readonly id: string;
  readonly kind: PromptKind;
  /** The account's username, or empty until the first run has asked. */
  readonly account: string;
  readonly atUtc: string;
  readonly lastRanAt: string | null;
  readonly lastSaid: string;
  readonly lastIssueNumber: number | null;
  readonly tokenRefreshedAt: string;
}
export const viewOf = (source: PromptSource): PromptSourceView => ({
  id: source.id,
  kind: source.kind,
  account: source.account,
  atUtc: source.atUtc,
  lastRanAt: source.lastRanAt,
  lastSaid: source.lastSaid,
  lastIssueNumber: source.lastIssueNumber,
  tokenRefreshedAt: source.tokenRefreshedAt,
});
export type PromptError = "not_found" | "no_such_source";
/** One of this repository's sources, by id — never another's. */
function ownedSource(
  app: App,
  repo: Repo,
  sourceId: string,
): PromptSource | undefined {
  const source = getPromptSource(app.db, sourceId);
  return source?.repoId === repo.id ? source : undefined;
}
export function listPromptSources(
  app: App,
  actor: User | undefined,
  repo: Repo,
): Result<PromptSourceView[], "not_found"> {
  const admin = requireRepoAdmin(app, actor, repo);
  if (!admin.ok) return admin;
  return ok(querySources(app.db, repo.id).map(viewOf));
}
export interface AddPromptInput {
  readonly kind: string;
  readonly token: string;
  readonly at: string;
}
/**
 * Connect an account. One of each kind per repository: a second Instagram
 * account would mean two tells a day from two places, and the page shows
 * one. The token is sealed on the way in and not shown again.
 */
export function addPromptSource(
  app: App,
  actor: User | undefined,
  repo: Repo,
  input: AddPromptInput,
): Result<
  PromptSourceView,
  "not_found" | "invalid_kind" | "already_connected" | AddPromptError
> {
  const admin = requireRepoAdmin(app, actor, repo);
  if (!admin.ok) return admin;
  if (input.kind !== "instagram") return err("invalid_kind");
  if (querySources(app.db, repo.id).some((s) => s.kind === input.kind))
    return err("already_connected");
  const added = insertSource(app.db, app.config.dataDir, {
    repoId: repo.id,
    kind: input.kind,
    token: input.token,
    atUtc: input.at,
    createdBy: admin.value.id,
  });
  if (!added.ok) return added;
  app.bus.append({
    kind: "prompt.source_added",
    repoId: repo.id,
    actorId: admin.value.id,
    payload: {
      source: added.value.id,
      kind: added.value.kind,
      at: added.value.atUtc,
    },
  });
  return ok(viewOf(added.value));
}
/** Look at Instagram now, whatever the hour; the source as the run left it. */
export async function runPromptSource(
  app: App,
  actor: User | undefined,
  repo: Repo,
  sourceId: string,
): Promise<Result<PromptSourceView, PromptError | "not_running">> {
  const admin = requireRepoAdmin(app, actor, repo);
  if (!admin.ok) return admin;
  if (ownedSource(app, repo, sourceId) === undefined)
    return err("no_such_source");
  const routine = promptsFor(app);
  if (routine === undefined) return err("not_running");
  const ran = await routine.runNow(sourceId);
  return ran === undefined ? err("no_such_source") : ok(viewOf(ran));
}
/** Disconnect. The token is forgotten; the issues already told stay. */
export function removePromptSource(
  app: App,
  actor: User | undefined,
  repo: Repo,
  sourceId: string,
): Result<void, PromptError> {
  const admin = requireRepoAdmin(app, actor, repo);
  if (!admin.ok) return admin;
  const source = ownedSource(app, repo, sourceId);
  if (source === undefined || !deleteSource(app.db, source.id))
    return err("no_such_source");
  app.bus.append({
    kind: "prompt.source_removed",
    repoId: repo.id,
    actorId: admin.value.id,
    payload: { source: source.id, kind: source.kind, account: source.account },
  });
  return ok();
}
@@ -26,6 +26,7 @@
export function eventAudience(kind: string): EventAudience {
    kind.startsWith("webhook.") ||
    kind.startsWith("app.env_") ||
    kind.startsWith("app.domain.") ||
    kind.startsWith("prompt.") ||
    kind === "repo.settings_updated"
  )
    return "admins";
@@ -0,0 +1,271 @@
/**
 * Prompt sources: where a repository's next tell comes from when nobody is
 * typing. One kind so far — an Instagram account whose latest Reel's top
 * comment becomes the crew's next tell, once a day (docs/APPS.md, "Prompts
 * from Instagram").
 *
 * The token is sealed at rest under the forge's key, bound to the row it
 * belongs to, and opened only for the run; nothing here ever returns it in
 * a listing. Pure data: no Instagram, no authz, no events — the routine in
 * `crew/prompts.ts` does the asking, and `actions/prompts.ts` the deciding.
 */
import type { Database } from "bun:sqlite";
import { id } from "../kernel/id.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { open, seal, type OpenError } from "../kernel/secret.ts";
export type PromptKind = "instagram";
export interface PromptSource {
  readonly id: string;
  readonly repoId: string;
  readonly kind: PromptKind;
  /** The account's username, learnt on the first run; empty until then. */
  readonly account: string;
  /** When the routine runs each day, `HH:MM` in UTC. */
  readonly atUtc: string;
  /** When the sealed token was pasted or last refreshed. */
  readonly tokenRefreshedAt: string;
  readonly createdBy: string | null;
  readonly createdAt: string;
  readonly lastRanAt: string | null;
  /** What the last run said, one sentence for a person. */
  readonly lastSaid: string;
  /** The Reel already told about, so the same one is never told twice. */
  readonly lastMediaId: string | null;
  readonly lastIssueNumber: number | null;
}
interface Row {
  id: string;
  repo_id: string;
  kind: string;
  account: string;
  at_utc: string;
  token_refreshed_at: string;
  created_by: string | null;
  created_at: string;
  last_ran_at: string | null;
  last_said: string;
  last_media_id: string | null;
  last_issue_number: number | null;
}
/** Every column but the sealed token: what a listing may carry. */
const COLUMNS = `id, repo_id, kind, account, at_utc, token_refreshed_at, created_by,
  created_at, last_ran_at, last_said, last_media_id, last_issue_number`;
const toSource = (r: Row): PromptSource => ({
  id: r.id,
  repoId: r.repo_id,
  kind: "instagram",
  account: r.account,
  atUtc: r.at_utc,
  tokenRefreshedAt: r.token_refreshed_at,
  createdBy: r.created_by,
  createdAt: r.created_at,
  lastRanAt: r.last_ran_at,
  lastSaid: r.last_said,
  lastMediaId: r.last_media_id,
  lastIssueNumber: r.last_issue_number,
});
const aad = (sourceId: string): string => `prompt-source:${sourceId}`;
const TOKEN_MAX = 1024;
export type AddPromptError = "invalid_at" | "invalid_token";
/** `HH:MM`, twenty-four hours, both parts zero-padded. */
export function isDailyTime(at: string): boolean {
  return /^(?:[01]\d|2[0-3]):[0-5]\d$/.test(at);
}
/**
 * A token as Instagram hands one out: printable, no spaces, not absurdly
 * long. Its shape is otherwise Instagram's business; the first run finds
 * out whether it is accepted, and says so.
 */
export function isPromptToken(token: string): boolean {
  return (
    token.length > 0 &&
    token.length <= TOKEN_MAX &&
    /^[\x21-\x7e]+$/.test(token)
  );
}
export function addPromptSource(
  db: Database,
  dataDir: string,
  input: {
    repoId: string;
    kind: PromptKind;
    token: string;
    atUtc: string;
    createdBy?: string | undefined;
    now?: Date | undefined;
  },
): Result<PromptSource, AddPromptError> {
  const atUtc = input.atUtc.trim();
  if (!isDailyTime(atUtc)) return err("invalid_at");
  const token = input.token.trim();
  if (!isPromptToken(token)) return err("invalid_token");
  const sourceId = id();
  const at = (input.now ?? new Date()).toISOString();
  db.query(
    `INSERT INTO prompt_source (id, repo_id, kind, token_enc, token_refreshed_at, at_utc, created_by, created_at)
     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?5)`,
  ).run(
    sourceId,
    input.repoId,
    input.kind,
    seal(dataDir, token, aad(sourceId)),
    at,
    atUtc,
    input.createdBy ?? null,
  );
  return ok(getPromptSource(db, sourceId)!);
}
export function getPromptSource(
  db: Database,
  sourceId: string,
): PromptSource | undefined {
  const row = db
    .query<Row, [string]>(`SELECT ${COLUMNS} FROM prompt_source WHERE id = ?1`)
    .get(sourceId);
  return row ? toSource(row) : undefined;
}
/** A repository's sources, oldest first. */
export function listPromptSources(
  db: Database,
  repoId: string,
): PromptSource[] {
  return db
    .query<
      Row,
      [string]
    >(`SELECT ${COLUMNS} FROM prompt_source WHERE repo_id = ?1 ORDER BY created_at, id`)
    .all(repoId)
    .map(toSource);
}
/**
 * The sources whose time has come today: `at_utc` at or before the clock's
 * `HH:MM`, and no run yet on the clock's date. A forge that was down at the
 * hour catches up on its next tick; one that ran already waits for tomorrow.
 */
export function duePromptSources(db: Database, now: Date): PromptSource[] {
  const iso = now.toISOString();
  return db
    .query<Row, [string, string]>(
      `SELECT ${COLUMNS} FROM prompt_source
       WHERE at_utc <= ?1 AND (last_ran_at IS NULL OR substr(last_ran_at, 1, 10) <> ?2)
       ORDER BY at_utc, created_at, id`,
    )
    .all(iso.slice(11, 16), iso.slice(0, 10))
    .map(toSource);
}
/**
 * Claim a source for a run, atomically: the row's `last_ran_at` moves to now
 * only if it has not run today — or unconditionally for a person's "Fetch
 * now". False means another run has it; the caller does nothing more.
 */
export function claimPromptRun(
  db: Database,
  sourceId: string,
  now: Date,
  o: { force?: boolean | undefined } = {},
): boolean {
  const iso = now.toISOString();
  const result = db
    .query(
      `UPDATE prompt_source SET last_ran_at = ?2
       WHERE id = ?1
         AND (?3 = 1 OR last_ran_at IS NULL OR substr(last_ran_at, 1, 10) <> substr(?2, 1, 10))`,
    )
    .run(sourceId, iso, o.force ? 1 : 0);
  return result.changes === 1;
}
/** The token, for a run. A value that will not open says so, never a throw. */
export function openPromptToken(
  db: Database,
  dataDir: string,
  sourceId: string,
): Result<string, "not_found" | OpenError> {
  const row = db
    .query<
      { token_enc: string },
      [string]
    >("SELECT token_enc FROM prompt_source WHERE id = ?1")
    .get(sourceId);
  if (!row) return err("not_found");
  return open(dataDir, row.token_enc, aad(sourceId));
}
/** After a refresh: the new token sealed, and the moment noted. */
export function storePromptToken(
  db: Database,
  dataDir: string,
  sourceId: string,
  token: string,
  now: Date,
): void {
  db.query(
    "UPDATE prompt_source SET token_enc = ?2, token_refreshed_at = ?3 WHERE id = ?1",
  ).run(sourceId, seal(dataDir, token, aad(sourceId)), now.toISOString());
}
export function setPromptAccount(
  db: Database,
  sourceId: string,
  username: string,
): void {
  db.query("UPDATE prompt_source SET account = ?2 WHERE id = ?1").run(
    sourceId,
    username,
  );
}
/**
 * What a run came to. The media id and the issue number are written only
 * when a Reel was actually told — a Reel with no comments yet leaves them
 * alone, so tomorrow's run looks at the same Reel again.
 */
export function recordPromptRun(
  db: Database,
  sourceId: string,
  run: {
    said: string;
    mediaId?: string | undefined;
    issueNumber?: number | undefined;
    now: Date;
  },
): PromptSource | undefined {
  db.query(
    `UPDATE prompt_source
       SET last_ran_at = ?2,
           last_said = ?3,
           last_media_id = COALESCE(?4, last_media_id),
           last_issue_number = COALESCE(?5, last_issue_number)
     WHERE id = ?1`,
  ).run(
    sourceId,
    run.now.toISOString(),
    run.said.slice(0, 400),
    run.mediaId ?? null,
    run.issueNumber ?? null,
  );
  return getPromptSource(db, sourceId);
}
export function removePromptSource(db: Database, sourceId: string): boolean {
  return (
    db.query("DELETE FROM prompt_source WHERE id = ?1").run(sourceId).changes >
    0
  );
}
@@ -898,4 +898,28 @@
export const migrations: readonly string[] = [
  );
  CREATE INDEX app_domain_app ON app_domain(app_id);
  `,
  // 33 — where a repository's next tell comes from when nobody is typing:
  // an Instagram account whose latest Reel's top comment becomes the crew's
  // next tell, once a day at `at_utc`. The token is sealed under the forge's
  // key, bound to the row; `last_media_id` is the Reel already told, so the
  // same one is never told twice; `last_said` is the last run's sentence.
  `
  CREATE TABLE prompt_source (
    id                 TEXT PRIMARY KEY,
    repo_id            TEXT NOT NULL REFERENCES repo(id) ON DELETE CASCADE,
    kind               TEXT NOT NULL,
    account            TEXT NOT NULL DEFAULT '',
    token_enc          TEXT NOT NULL,
    token_refreshed_at TEXT NOT NULL,
    at_utc             TEXT NOT NULL,
    created_by         TEXT REFERENCES user(id) ON DELETE SET NULL,
    created_at         TEXT NOT NULL,
    last_ran_at        TEXT,
    last_said          TEXT NOT NULL DEFAULT '',
    last_media_id      TEXT,
    last_issue_number  INTEGER
  );
  CREATE INDEX prompt_source_repo ON prompt_source(repo_id);
  `,
];
@@ -0,0 +1,244 @@
/**
 * Instagram, as the prompt routine sees it: who the token belongs to, the
 * newest Reel, its top-level comments, and a fresh token. The Instagram API
 * with Instagram Login (Meta's "Business Login for Instagram"): a
 * professional account, a long-lived user token, no Facebook Page.
 *
 * The interface is what the routine is written against; `graphInstagram`
 * is the one that talks to Meta, and a test hands the routine a fake. The
 * token travels only in the query string of a request to Meta's host, as
 * the API asks, and is never logged or put in a sentence.
 */
import { redactSecrets } from "../kernel/log.ts";
/** A Reel, or the newest video when the API does not say which are Reels. */
export interface Reel {
  readonly id: string;
  readonly permalink: string;
  /** As Instagram gives it, ISO 8601. */
  readonly timestamp: string;
  readonly caption: string;
  readonly commentsCount: number;
}
/** A top-level comment. */
export interface Comment {
  readonly id: string;
  readonly text: string;
  readonly username: string;
  readonly timestamp: string;
  readonly likeCount: number;
}
export interface InstagramClient {
  me(token: string): Promise<{ id: string; username: string }>;
  latestReel(token: string): Promise<Reel | undefined>;
  comments(token: string, mediaId: string): Promise<Comment[]>;
  refresh(token: string): Promise<{ token: string }>;
}
/**
 * What Meta answered with instead of data. `code` is Meta's: 190 is a
 * token that is invalid or has expired, the one a person must act on.
 */
export class InstagramError extends Error {
  constructor(
    readonly code: number,
    message: string,
    readonly type = "",
  ) {
    super(message);
    this.name = "InstagramError";
  }
}
/** The token is no good: the person who pasted it must make another. */
export const TOKEN_REFUSED = 190;
/**
 * One sentence for a run that met an error, for the source's `last_said`.
 * Never the token, never a stack.
 */
export function instagramSaid(error: unknown): string {
  if (error instanceof InstagramError) {
    if (error.code === TOKEN_REFUSED)
      return "Instagram no longer accepts the token; connect the account again.";
    return `Instagram answered: ${oneSentence(redactSecrets(error.message))}`;
  }
  if (error instanceof Error && error.name === "TimeoutError")
    return "Instagram did not answer within ten seconds.";
  return `The run failed: ${oneSentence(redactSecrets(error instanceof Error ? error.message : String(error)))}`;
}
function oneSentence(text: string): string {
  const line = text.replace(/\s+/g, " ").trim();
  const cut = line.length > 200 ? `${line.slice(0, 199).trimEnd()}…` : line;
  return /[.!?…]$/.test(cut) ? cut : `${cut}.`;
}
/**
 * The comment that becomes the tell: the most liked, and of those the
 * earliest. A comment with nothing in it is nobody's prompt.
 */
export function topComment(comments: readonly Comment[]): Comment | undefined {
  let top: Comment | undefined;
  for (const comment of comments) {
    if (comment.text.trim() === "") continue;
    if (
      top === undefined ||
      comment.likeCount > top.likeCount ||
      (comment.likeCount === top.likeCount && comment.timestamp < top.timestamp)
    )
      top = comment;
  }
  return top;
}
// ---- the real one ----
const HOST = "https://graph.instagram.com";
const VERSION = "v25.0";
const TIMEOUT_MS = 10_000;
/** How many pages of comments are read before the top is taken as found. */
export const COMMENT_PAGES = 4;
const COMMENTS_PER_PAGE = 50;
const MEDIA_PER_PAGE = 50;
type Json = Record<string, unknown>;
interface MediaItem {
  id?: unknown;
  media_type?: unknown;
  media_product_type?: unknown;
  permalink?: unknown;
  timestamp?: unknown;
  caption?: unknown;
  comments_count?: unknown;
}
interface CommentItem {
  id?: unknown;
  text?: unknown;
  username?: unknown;
  timestamp?: unknown;
  like_count?: unknown;
}
const str = (v: unknown): string => (typeof v === "string" ? v : "");
const num = (v: unknown): number => (typeof v === "number" ? v : 0);
export function graphInstagram(fetchFn: typeof fetch = fetch): InstagramClient {
  const get = async (
    path: string,
    params: Record<string, string>,
  ): Promise<Json> => {
    const url = new URL(path, HOST);
    for (const [key, value] of Object.entries(params))
      url.searchParams.set(key, value);
    const response = await fetchFn(url, {
      signal: AbortSignal.timeout(TIMEOUT_MS),
      headers: { accept: "application/json" },
    });
    const body = (await response.json().catch(() => ({}))) as Json;
    const failure = body["error"];
    if (typeof failure === "object" && failure !== null) {
      const e = failure as Json;
      throw new InstagramError(
        num(e["code"]),
        str(e["message"]) || `Instagram answered ${response.status}`,
        str(e["type"]),
      );
    }
    if (!response.ok)
      throw new InstagramError(
        response.status,
        `Instagram answered ${response.status}`,
      );
    return body;
  };
  const items = <T>(body: Json): T[] =>
    Array.isArray(body["data"]) ? (body["data"] as T[]) : [];
  const after = (body: Json): string | undefined => {
    const paging = body["paging"];
    if (typeof paging !== "object" || paging === null) return undefined;
    const cursors = (paging as Json)["cursors"];
    if (typeof cursors !== "object" || cursors === null) return undefined;
    const cursor = str((cursors as Json)["after"]);
    return cursor === "" ? undefined : cursor;
  };
  return {
    async me(token) {
      const body = await get(`/${VERSION}/me`, {
        fields: "id,username",
        access_token: token,
      });
      return { id: str(body["id"]), username: str(body["username"]) };
    },
    async latestReel(token) {
      const body = await get(`/${VERSION}/me/media`, {
        fields:
          "id,media_type,media_product_type,permalink,timestamp,caption,comments_count",
        limit: String(MEDIA_PER_PAGE),
        access_token: token,
      });
      const media = items<MediaItem>(body);
      // Newest first. Where the API says which items are Reels, that is
      // the answer; where it does not (Instagram Login may leave the field
      // out), the newest video stands in.
      const says = media.some((m) => typeof m.media_product_type === "string");
      const found = says
        ? media.find((m) => m.media_product_type === "REELS")
        : media.find((m) => m.media_type === "VIDEO");
      if (found === undefined || str(found.id) === "") return undefined;
      return {
        id: str(found.id),
        permalink: str(found.permalink),
        timestamp: str(found.timestamp),
        caption: str(found.caption),
        commentsCount: num(found.comments_count),
      };
    },
    async comments(token, mediaId) {
      const out: Comment[] = [];
      let cursor: string | undefined;
      for (let page = 0; page < COMMENT_PAGES; page++) {
        const body = await get(
          `/${VERSION}/${encodeURIComponent(mediaId)}/comments`,
          {
            fields: "id,text,username,timestamp,like_count",
            limit: String(COMMENTS_PER_PAGE),
            access_token: token,
            ...(cursor === undefined ? {} : { after: cursor }),
          },
        );
        for (const c of items<CommentItem>(body))
          out.push({
            id: str(c.id),
            text: str(c.text),
            username: str(c.username),
            timestamp: str(c.timestamp),
            likeCount: num(c.like_count),
          });
        cursor = after(body);
        if (cursor === undefined) break;
      }
      return out;
    },
    async refresh(token) {
      const body = await get("/refresh_access_token", {
        grant_type: "ig_refresh_token",
        access_token: token,
      });
      const fresh = str(body["access_token"]);
      if (fresh === "")
        throw new InstagramError(0, "the refresh answered with no token");
      return { token: fresh };
    },
  };
}
@@ -0,0 +1,265 @@
/**
 * The prompt routine: once a day, for every repository that asked, the top
 * comment on the account's latest Reel becomes the crew's next tell
 * (docs/APPS.md, "Prompts from Instagram").
 *
 * Every minute the clock is compared with each source's hour; a source
 * whose hour has passed and that has not run today runs. A run reads the
 * latest Reel, takes its most-liked comment, and tells the crew as a
 * person would from the studio box — `tellCrew` opens the issue and routes
 * it. Nothing is invented: no Reel, no new Reel, or no comment yet is a
 * sentence on the settings page and another look tomorrow. One source runs
 * at a time, `Fetch now` included, and a run that fails is a sentence too,
 * never a throw into the timer.
 */
import type { App } from "../app.ts";
import { tellCrew } from "../actions/crew.ts";
import {
  duePromptSources,
  getPromptSource,
  openPromptToken,
  recordPromptRun,
  setPromptAccount,
  storePromptToken,
  type PromptSource,
  claimPromptRun,
} from "../core/prompts.ts";
import { getRepoById } from "../core/repos.ts";
import { getUserById } from "../core/users.ts";
import { createLog, redactSecrets } from "../kernel/log.ts";
import {
  instagramSaid,
  topComment,
  type Comment,
  type InstagramClient,
  type Reel,
} from "./instagram.ts";
const log = createLog("prompts");
/** How often the clock is looked at. */
/** How long a shutdown waits for a run in flight before going on without it. */
const STOP_DEADLINE_MS = 15_000;
const TICK_MS = 60_000;
/**
 * A long-lived token lives sixty days and may be refreshed once it is a day
 * old; at fifty the forge refreshes it, leaving a ten-day margin for a
 * forge that is down.
 */
export const REFRESH_AFTER_DAYS = 50;
const DAY_MS = 24 * 3_600_000;
export interface PromptRoutineOptions {
  readonly client: InstagramClient;
  /** The clock, for tests. @default the wall clock */
  readonly now?: (() => Date) | undefined;
  /** @default a minute */
  readonly everyMs?: number | undefined;
  /** How long `stop()` waits for a run in flight. */
  readonly stopDeadlineMs?: number | undefined;
}
export interface PromptRoutineHandle {
  /** Stop the clock; a run in flight finishes first. */
  readonly stop: () => Promise<void>;
  /** Run every source whose hour has come and that has not run today. */
  readonly runDue: (now?: Date) => Promise<void>;
  /** Run one source now, whatever the hour; the source after, or nothing for an unknown id. */
  readonly runNow: (sourceId: string) => Promise<PromptSource | undefined>;
}
const handles = new WeakMap<App, PromptRoutineHandle>();
/** The routine of this forge, if one was started. */
export const promptsFor = (app: App): PromptRoutineHandle | undefined =>
  handles.get(app);
export function startPromptRoutine(
  app: App,
  options: PromptRoutineOptions,
): PromptRoutineHandle {
  const now = options.now ?? (() => new Date());
  let stopped = false;
  // One source at a time: the due sweep and a `Fetch now` join the same
  // line, so a run never overlaps another on the same row.
  let line: Promise<unknown> = Promise.resolve();
  const enqueue = <T>(work: () => Promise<T>): Promise<T> => {
    const next = line.then(work);
    line = next.catch(() => undefined);
    return next;
  };
  const runDue = (at = now()): Promise<void> =>
    enqueue(async () => {
      for (const source of duePromptSources(app.db, at)) {
        if (stopped) return;
        await runSource(app, options.client, source, at);
      }
    });
  const timer = setInterval(() => {
    if (stopped) return;
    runDue().catch((error) =>
      log.error("prompt sweep failed", { error: String(error) }),
    );
  }, options.everyMs ?? TICK_MS);
  const handle: PromptRoutineHandle = {
    runDue,
    runNow: (sourceId) =>
      enqueue(async () => {
        const source = getPromptSource(app.db, sourceId);
        if (source === undefined) return undefined;
        return runSource(app, options.client, source, now(), true);
      }),
    stop: async () => {
      stopped = true;
      clearInterval(timer);
      // A run in flight is waited for, but not forever: shutdown has its
      // own patience, and Instagram is not allowed to spend it.
      await Promise.race([
        line,
        Bun.sleep(options.stopDeadlineMs ?? STOP_DEADLINE_MS),
      ]);
      if (handles.get(app) === handle) handles.delete(app);
    },
  };
  handles.set(app, handle);
  return handle;
}
/** The likes, in words. */
const likes = (n: number): string => (n === 1 ? "1 like" : `${n} likes`);
/** The Reel's day, as `YYYY-MM-DD`, from Instagram's timestamp. */
const dayOf = (reel: Reel): string => reel.timestamp.slice(0, 10);
/** What the settings page shows of a told comment: its first line, shortly. */
function shortly(text: string): string {
  const line = text.trim().split(/\n/)[0]!.trim();
  return line.length <= 60 ? line : `${line.slice(0, 60).trimEnd()}…`;
}
/**
 * The tell, as the crew reads it: the comment itself first — `tellCrew`
 * makes its first line the title — and where it came from beneath.
 */
export function tellText(reel: Reel, comment: Comment): string {
  return `${comment.text.trim()}\n\nFrom Instagram: the top comment (${likes(comment.likeCount)}) by @${comment.username} on the Reel of ${dayOf(reel)}. ${reel.permalink}`.trim();
}
/**
 * One run of one source. Every exit is a sentence recorded on the row; the
 * media id is recorded only when the Reel was told, so a Reel that has no
 * comments yet is looked at again tomorrow.
 */
async function runSource(
  app: App,
  client: InstagramClient,
  source: PromptSource,
  now: Date,
  /** A person's "Fetch now" runs whatever the day; the sweep does not. */
  force = false,
): Promise<PromptSource | undefined> {
  // Every token this run has held. A sentence about an error may quote a
  // request, and a request carries the token: nothing recorded — and so
  // nothing listed or shown — may hold it, or anything shaped like one.
  const tokens: string[] = [];
  const clean = (said: string): string =>
    redactSecrets(
      tokens.reduce((text, t) => (t === "" ? text : text.split(t).join("[token]")), said),
    );
  const record = (run: {
    said: string;
    mediaId?: string;
    issueNumber?: number;
  }) => recordPromptRun(app.db, source.id, { ...run, said: clean(run.said), now });
  // The row is claimed before any network work: two forges over one data
  // directory, or two ticks over one row, must not tell the crew twice.
  if (!claimPromptRun(app.db, source.id, now, { force })) return undefined;
  try {
    const opened = openPromptToken(app.db, app.config.dataDir, source.id);
    if (!opened.ok)
      return record({
        said:
          opened.error === "not_found"
            ? "The source is gone."
            : "The token would not open; connect the account again.",
      });
    let token = opened.value;
    tokens.push(token);
    if (
      now.getTime() - Date.parse(source.tokenRefreshedAt) >
      REFRESH_AFTER_DAYS * DAY_MS
    ) {
      const fresh = await client.refresh(token);
      storePromptToken(app.db, app.config.dataDir, source.id, fresh.token, now);
      token = fresh.token;
      tokens.push(token);
    }
    if (source.account === "") {
      const me = await client.me(token);
      if (me.username !== "") setPromptAccount(app.db, source.id, me.username);
    }
    const reel = await client.latestReel(token);
    if (reel === undefined) return record({ said: "No Reel yet." });
    if (reel.id === source.lastMediaId)
      return record({
        said:
          source.lastIssueNumber === null
            ? `No new Reel since ${dayOf(reel)}.`
            : `No new Reel since ${dayOf(reel)}; the last one was told as #${source.lastIssueNumber}.`,
      });
    const top = topComment(await client.comments(token, reel.id));
    if (top === undefined)
      return record({ said: "The latest Reel has no comments yet." });
    const repo = getRepoById(app.db, source.repoId);
    if (repo === undefined) return record({ said: "The repository is gone." });
    const creator =
      source.createdBy === null
        ? undefined
        : getUserById(app.db, source.createdBy);
    const told = await tellCrew(app, creator, repo, tellText(reel, top));
    if (!told.ok)
      return record({
        said:
          told.error === "unauthorized"
            ? "The person who connected the account is gone; connect it again."
            : `The crew could not be told (${told.error}).`,
      });
    const number = told.value.issue.number;
    app.bus.append({
      kind: "prompt.told",
      repoId: repo.id,
      payload: {
        source: source.id,
        kind: source.kind,
        mediaId: reel.id,
        commentId: top.id,
        issue: number,
      },
    });
    const who = `"${shortly(top.text)}" — @${top.username}, ${likes(top.likeCount)}`;
    return record({
      // Honest about who heard it: an issue opens with nobody to route it
      // to when the crew is empty, and that is not "told the crew".
      said:
        told.value.routed === undefined
          ? `Opened #${number}: ${who}; nobody on the crew to take it yet.`
          : `Told the crew #${number}: ${who}.`,
      mediaId: reel.id,
      issueNumber: number,
    });
  } catch (error) {
    log.warn("prompt run failed", { source: source.id, error: String(error) });
    return record({ said: instagramSaid(error) });
  }
}
@@ -69,6 +69,12 @@
export function eventVerb(event: ForgeEvent): string {
    if (kind === "app.domain.verified") return `verified the domain ${which}`;
    return `removed the domain ${which}`;
  }
  if (kind === "prompt.told") {
    const issue = payload["issue"];
    return typeof issue === "number"
      ? `told the crew the top Instagram comment as #${issue}`
      : "told the crew the top Instagram comment";
  }
  return WORDS[kind] ?? "acted on this repository";
}
@@ -78,7 +84,9 @@
export function eventActor(
  actorName: string | undefined,
): string {
  if (actorName !== undefined) return actorName;
  return event.kind.startsWith("run.") || event.kind.startsWith("app.")
  return event.kind.startsWith("run.") ||
    event.kind.startsWith("app.") ||
    event.kind.startsWith("prompt.")
    ? "the forge"
    : "someone";
}
@@ -120,4 +128,6 @@
const WORDS: Record<string, string> = {
  "app.created": "made it an app",
  "app.updated": "changed the app's settings",
  "app.deleted": "stopped serving it as an app",
  "prompt.source_added": "connected an Instagram account to prompt the crew",
  "prompt.source_removed": "disconnected the Instagram account",
};
@@ -159,6 +159,12 @@
import {
  listAppDomains,
  removeAppDomain,
} from "../actions/domains.ts";
import {
  addPromptSource,
  listPromptSources,
  removePromptSource,
  runPromptSource,
} from "../actions/prompts.ts";
import { listDomains } from "../core/domains.ts";
import type { Database } from "bun:sqlite";
import {
@@ -2912,6 +2918,68 @@
export function apiRoutes(router: Router<Handler>): void {
    },
  );
  // Where the crew's next tell comes from when nobody is typing
  // (docs/APPS.md, "Prompts from Instagram"). Admin scope and admin over
  // the repository; the token goes in once and never comes back out.
  router.add("GET", "/api/v1/repos/:owner/:name/prompts", (ctx) => {
    const denied = requireScope(ctx, "admin");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const listed = listPromptSources(ctx.app, ctx.auth.user, repo);
    if (!listed.ok) return respondAccess(listed.error, 422);
    return json({ items: listed.value, next_cursor: null });
  });
  router.add("POST", "/api/v1/repos/:owner/:name/prompts", async (ctx) => {
    const denied = requireScope(ctx, "admin");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const input = await body(ctx.request);
    const added = addPromptSource(ctx.app, ctx.auth.user, repo, {
      kind: str(input.kind),
      token: str(input.token),
      at: str(input.at),
    });
    if (!added.ok) return respondAccess(added.error, 422);
    return json(added.value, 201);
  });
  router.add(
    "POST",
    "/api/v1/repos/:owner/:name/prompts/:id/run",
    async (ctx) => {
      const denied = requireScope(ctx, "admin");
      if (denied) return denied;
      const repo = loadRepo(ctx);
      if (!repo) return notFound();
      const ran = await runPromptSource(
        ctx.app,
        ctx.auth.user,
        repo,
        ctx.params.id ?? "",
      );
      if (!ran.ok) return respondAccess(ran.error, 422);
      return json(ran.value);
    },
  );
  router.add("DELETE", "/api/v1/repos/:owner/:name/prompts/:id", (ctx) => {
    const denied = requireScope(ctx, "admin");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const removed = removePromptSource(
      ctx.app,
      ctx.auth.user,
      repo,
      ctx.params.id ?? "",
    );
    if (!removed.ok) return respondAccess(removed.error, 422);
    return json({}, 200);
  });
  // The app's environment: names in, names out, and never a value back.
  // `:var`, not `:name` — `:name` is the repository's.
  router.add("GET", "/api/v1/repos/:owner/:name/app/env", (ctx) => {
@@ -180,6 +180,10 @@
import {
  labelDelete,
  labelUpdate,
  labelsPage,
  promptSourceAdd,
  promptSourceDelete,
  promptSourceRun,
  promptsSettingsPage,
  repoDelete,
  settingsPage,
  settingsUpdate,
@@ -809,6 +813,14 @@
export function buildRouter(): Router<Handler> {
    "/:owner/:name/settings/app/domains/:host/delete",
    appDomainDelete,
  );
  router.add("GET", "/:owner/:name/settings/prompts", promptsSettingsPage);
  router.add("POST", "/:owner/:name/settings/prompts", promptSourceAdd);
  router.add("POST", "/:owner/:name/settings/prompts/:id/run", promptSourceRun);
  router.add(
    "POST",
    "/:owner/:name/settings/prompts/:id/delete",
    promptSourceDelete,
  );
  router.add("GET", "/:owner/:name/settings/crew", crewSettingsPage);
  router.add("POST", "/:owner/:name/settings/crew", crewAdd);
  router.add(
@@ -24,6 +24,8 @@
import { health } from "./http/health.ts";
import { STALE_AFTER_MS } from "./runs/lease.ts";
import { startCrew } from "./crew/dispatch.ts";
import { typeSafeDecider } from "./crew/decide.ts";
import { graphInstagram } from "./crew/instagram.ts";
import { startPromptRoutine } from "./crew/prompts.ts";
import { pruneTokens } from "./core/tokens.ts";
// `forge hook <name>` re-enters here from a git hook stub. It relays to the
@@ -180,6 +182,10 @@
const crew = appsOn
        : { configDir: process.env.FORGE_CLAUDE_CONFIG_DIR }),
    })
  : undefined;
// Prompts from Instagram (docs/APPS.md): once a day, for each repository
// that connected an account, the top comment on its latest Reel is told to
// the crew. A minute's clock; nothing leaves the box until a source exists.
const prompts = startPromptRoutine(app, { client: graphInstagram() });
// The webhook delivery worker: poll the outbox for due deliveries. The event
// row is the source of truth, so a missed tick only delays delivery, never
@@ -265,6 +271,7 @@
function shutdown(): void {
  clearInterval(syncTimer);
  clearInterval(leaseTimer);
  Promise.all([
    prompts.stop(),
    crew?.stop({ drain: true }),
    apps?.stop(),
    checks?.stop(),
@@ -411,6 +411,15 @@
const DESTRUCTIVE: {
      phrase: "",
    }),
  },
  {
    pattern: /^\/([^/]+)\/([^/]+)\/settings\/prompts\/([^/]+)\/delete$/,
    describe: (m) => ({
      verb: "Disconnect",
      title: "Disconnect Instagram?",
      detail: `The daily tell from Instagram stops for ${m[1]}/${m[2]}, and the token is forgotten. The issues it already told stay.`,
      phrase: "",
    }),
  },
  {
    pattern: /^\/([^/]+)\/([^/]+)\/settings\/labels\/([^/]+)\/delete$/,
    describe: (m) => ({
@@ -22,7 +22,15 @@
import {
  removeAppDomain,
  type AppDomainView,
} from "../../actions/domains.ts";
import {
  addPromptSource,
  listPromptSources,
  removePromptSource,
  runPromptSource,
  type PromptSourceView,
} from "../../actions/prompts.ts";
import type { DnsRecord } from "../../apps/domains.ts";
import { REFRESH_AFTER_DAYS } from "../../crew/prompts.ts";
import {
  listAppEnvNames,
  NAME_MAX,
@@ -97,6 +105,7 @@
import {
  row,
  selectField,
  time,
  timeAgo,
  userLink,
} from "../ui.ts";
import { crewReadiness } from "./crew.ts";
@@ -106,6 +115,7 @@
type Section =
  | "general"
  | "app"
  | "crew"
  | "prompts"
  | "autonomy"
  | "labels"
  | "hooks"
@@ -139,6 +149,12 @@
function sections(base: string, active: Section) {
      icon: "bot" as const,
      current: active === "crew",
    },
    {
      label: "Prompts",
      href: `${base}/settings/prompts`,
      icon: "comment" as const,
      current: active === "prompts",
    },
    {
      label: "Autonomy",
      href: `${base}/settings/autonomy`,
@@ -921,6 +937,233 @@
function redeploying(ctx: Ctx, how: string): string {
    : ` Production and every preview are starting again ${how}.`;
}
// ---- prompts ----
const PROMPT_ERRORS: Record<string, string> = {
  invalid_at: "The time is hours and minutes in UTC, like 15:00.",
  invalid_token:
    "Paste the long-lived token as Instagram gave it: one line, no spaces.",
  invalid_kind: "Only Instagram is known here.",
  already_connected:
    "An Instagram account is already connected here. Remove it first.",
  no_such_source: "No account by that id.",
  not_running: "The prompt routine is not running on this forge.",
};
/** The day the forge will refresh a token pasted or refreshed at `iso`. */
function refreshDay(iso: string): string {
  return new Date(Date.parse(iso) + REFRESH_AFTER_DAYS * 24 * 3_600_000)
    .toISOString()
    .slice(0, 10);
}
/**
 * The Instagram card: the account and what the last run said when one is
 * connected, the form when none is. Beneath it, the one-time steps at Meta,
 * because the forge cannot take them for anyone. The token is a password
 * field on the way in and nowhere on the way out.
 */
function promptsView(base: string, sources: PromptSourceView[]): Html {
  const source = sources.find((s) => s.kind === "instagram");
  const at = (id: string) =>
    `${base}/settings/prompts/${encodeURIComponent(id)}`;
  const body =
    source === undefined
      ? html`<div class="card-body">
            <p class="muted small">
              Once a day, the top comment on your latest Reel becomes the crew's
              next tell.
            </p>
          </div>
          <form
            class="card-body"
            method="post"
            action="${base}/settings/prompts"
          >
            ${formField({
              label: "Token",
              name: "token",
              type: "password",
              hint: "A long-lived Instagram token. The forge seals it, refreshes it before it expires, and never shows it again.",
              required: true,
              autocomplete: "off",
              mono: true,
            })}
            ${formField({
              label: "Every day at … UTC",
              name: "at",
              type: "time",
              value: "15:00",
              required: true,
            })}
            <div class="form-actions">
              ${btn("Add", { variant: "primary", icon: "plus" })}
            </div>
          </form>`
      : html`<ul class="list">
          <li>
            <div class="row">
              <span class="row-lead">${icon("comment")}</span>
              <span class="row-main">
                <span class="row-title"
                  >${source.account === ""
                    ? html`<span class="muted">not read yet</span>`
                    : `@${source.account}`}
                  ${badge(`every day at ${source.atUtc} UTC`)}</span
                >
                <span class="row-meta"
                  >${source.lastRanAt === null
                    ? "Has not run yet."
                    : html`Last ran ${time(source.lastRanAt)}.
                      ${source.lastSaid}`}</span
                >
                <span class="row-meta"
                  >Token refreshed ${timeAgo(source.tokenRefreshedAt)}; the
                  forge refreshes it again around
                  ${refreshDay(source.tokenRefreshedAt)}.</span
                >
              </span>
              <span class="row-trail">
                <form method="post" action="${at(source.id)}/run">
                  ${btn("Fetch now", { size: "sm", icon: "sync" })}
                </form>
                ${confirmAction({
                  action: `${at(source.id)}/delete`,
                  verb: "Remove",
                  size: "sm",
                })}
              </span>
            </div>
          </li>
        </ul>`;
  return html`${card(body, {
    head: html`${icon("comment")}
      <h2>Instagram</h2>`,
    pad: false,
  })}
  ${card(
    html`<p class="muted small">
        The one-time steps at Meta, for a professional account of your own. None
        of them needs App Review.
      </p>
      <ol class="steps">
        <li>
          Make the Instagram account a professional one — Business or Creator —
          in the Instagram app's settings.
        </li>
        <li>
          At developers.facebook.com, make a Meta app and add the Instagram
          product with <b>Business Login for Instagram</b>. No Facebook Page is
          needed.
        </li>
        <li>
          Get a token for the account with the scopes
          <span class="mono">instagram_business_basic</span> and
          <span class="mono">instagram_business_manage_comments</span>.
        </li>
        <li>
          Exchange it for a long-lived token, the one that lives sixty days; the
          product's docs show the one call.
        </li>
        <li>
          Paste the long-lived token above. The forge refreshes it before it
          expires, and the paste is never shown again.
        </li>
      </ol>`,
    { head: html`<h2>Getting a token</h2>` },
  )}`;
}
// GET /:owner/:name/settings/prompts
export function promptsSettingsPage(ctx: Ctx): Response {
  const repo = loadAdminRepo(ctx);
  if (!repo) return repoNotFound(ctx);
  const listed = listPromptSources(ctx.app, ctx.auth.user, repo);
  return settingsPageResponse(
    ctx,
    repo,
    "prompts",
    "Prompts",
    promptsView(repoBase(repo), listed.ok ? listed.value : []),
  );
}
// POST /:owner/:name/settings/prompts — connect an account.
export async function promptSourceAdd(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo, form } = gate;
  const added = addPromptSource(ctx.app, ctx.auth.user, repo, {
    kind: "instagram",
    token: field(form, "token"),
    at: field(form, "at"),
  });
  if (!added.ok && added.error === "not_found") return repoNotFound(ctx);
  return flashTo(
    ctx,
    `${repoBase(repo)}/settings/prompts`,
    added.ok
      ? {
          message: `Instagram is connected. Every day at ${added.value.atUtc} UTC the top comment on the latest Reel is told to the crew; press Fetch now to try it.`,
        }
      : {
          tone: "danger",
          message:
            PROMPT_ERRORS[added.error] ?? "The account could not be connected.",
        },
  );
}
// POST /:owner/:name/settings/prompts/:id/run — look at Instagram now.
export async function promptSourceRun(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo } = gate;
  const ran = await runPromptSource(
    ctx.app,
    ctx.auth.user,
    repo,
    ctx.params.id ?? "",
  );
  if (!ran.ok && ran.error === "not_found") return repoNotFound(ctx);
  return flashTo(
    ctx,
    `${repoBase(repo)}/settings/prompts`,
    ran.ok
      ? {
          ...(ran.value.lastSaid.startsWith("Told the crew")
            ? {}
            : { tone: "attn" as const }),
          message: ran.value.lastSaid,
        }
      : {
          tone: "danger",
          message: PROMPT_ERRORS[ran.error] ?? "No account by that id.",
        },
  );
}
// POST /:owner/:name/settings/prompts/:id/delete
export async function promptSourceDelete(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo } = gate;
  const removed = removePromptSource(
    ctx.app,
    ctx.auth.user,
    repo,
    ctx.params.id ?? "",
  );
  if (!removed.ok && removed.error === "not_found") return repoNotFound(ctx);
  return flashTo(
    ctx,
    `${repoBase(repo)}/settings/prompts`,
    removed.ok
      ? { message: "Instagram is disconnected. The token is forgotten." }
      : { tone: "danger", message: "No account by that id." },
  );
}
// ---- crew ----
// GET /:owner/:name/settings/crew
@@ -107,6 +107,8 @@
describe("who an event is for", () => {
    expect(eventAudience("app.env_set")).toBe("admins");
    expect(eventAudience("app.env_deleted")).toBe("admins");
    expect(eventAudience("repo.settings_updated")).toBe("admins");
    expect(eventAudience("prompt.told")).toBe("admins");
    expect(eventAudience("prompt.source_added")).toBe("admins");
    expect(eventAudience("repo.pinned")).toBe("actor");
    expect(eventAudience("push")).toBe("readers");
    expect(eventAudience("a.kind.nobody.classified")).toBe("readers");
@@ -0,0 +1,1072 @@
/**
 * Prompts from Instagram (docs/APPS.md): once a day, the top comment on the
 * account's latest Reel becomes the crew's next tell. Instagram is a fake
 * the test scripts, the clock is the test's, and nothing here touches the
 * network — the real client is exercised against a fake `fetch`.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { addToCrew, createAgent, removeFromCrew } from "../src/actions/crew.ts";
import { createRepo } from "../src/actions/repos.ts";
import { createApp, type App } from "../src/app.ts";
import { listEvents } from "../src/core/events.ts";
import { getIssue, listIssues } from "../src/core/issues.ts";
import {
  addPromptSource,
  getPromptSource,
  isDailyTime,
  claimPromptRun,
  listPromptSources,
  openPromptToken,
} from "../src/core/prompts.ts";
import type { Repo } from "../src/core/repos.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser, type User } from "../src/core/users.ts";
import {
  COMMENT_PAGES,
  graphInstagram,
  InstagramError,
  instagramSaid,
  topComment,
  type Comment,
  type InstagramClient,
  type Reel,
} from "../src/crew/instagram.ts";
import {
  startPromptRoutine,
  type PromptRoutineHandle,
} from "../src/crew/prompts.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
/** Distinctive enough that its presence anywhere is unmistakable. */
const TOKEN = "IGAAQzx7k9p2m4-long-lived-token-for-the-test-QQ";
const FRESH = "IGAAQfresh-token-after-the-refresh-QQ";
const at = (iso: string): Comment["timestamp"] => iso;
const comment = (
  id: string,
  text: string,
  likeCount: number,
  timestamp: string,
  username = "someone",
): Comment => ({ id, text, username, timestamp, likeCount });
const reelOf = (id: string, day: string): Reel => ({
  id,
  permalink: `https://www.instagram.com/reel/${id}/`,
  timestamp: `${day}T18:00:00+0000`,
  caption: "new level",
  commentsCount: 3,
});
/** A page with its whitespace collapsed, for asserting on a sentence. */
const words = (html: string): string => html.replace(/\s+/g, " ");
describe("topComment", () => {
  test("picks the most liked, ties to the earliest, and ignores empty text", () => {
    const a = comment(
      "a",
      "later, same likes",
      5,
      at("2026-09-27T18:10:00+0000"),
    );
    const b = comment(
      "b",
      "earlier, same likes",
      5,
      at("2026-09-27T18:01:00+0000"),
    );
    const c = comment("c", "fewer likes", 2, at("2026-09-27T18:00:00+0000"));
    const blank = comment("d", "   ", 99, at("2026-09-27T17:00:00+0000"));
    expect(topComment([c, a, b, blank])?.id).toBe("b");
    expect(topComment([c])?.id).toBe("c");
    expect(topComment([blank])).toBeUndefined();
    expect(topComment([])).toBeUndefined();
  });
});
describe("the Instagram client", () => {
  /** A fetch that answers from a script and remembers what it was asked. */
  const scripted = (
    answer: (url: URL) => { status?: number; body: unknown },
  ) => {
    const asked: { url: URL; signal: AbortSignal | null | undefined }[] = [];
    const fetchFn = ((input: URL | Request | string, init?: RequestInit) => {
      const url =
        input instanceof URL
          ? input
          : new URL(typeof input === "string" ? input : input.url);
      asked.push({ url, signal: init?.signal });
      const { status, body } = answer(url);
      return Promise.resolve(
        new Response(JSON.stringify(body), {
          status: status ?? 200,
          headers: { "content-type": "application/json" },
        }),
      );
    }) as unknown as typeof fetch;
    return { asked, client: graphInstagram(fetchFn) };
  };
  test("asks Meta's host with the token in the query, and a timeout on every call", async () => {
    const { asked, client } = scripted(() => ({
      body: { id: "17841400000000000", username: "gamehandle" },
    }));
    expect(await client.me(TOKEN)).toEqual({
      id: "17841400000000000",
      username: "gamehandle",
    });
    const [first] = asked;
    expect(first?.url.origin).toBe("https://graph.instagram.com");
    expect(first?.url.pathname).toBe("/v25.0/me");
    expect(first?.url.searchParams.get("fields")).toBe("id,username");
    expect(first?.url.searchParams.get("access_token")).toBe(TOKEN);
    expect(first?.signal).toBeInstanceOf(AbortSignal);
  });
  test("the latest Reel: the newest REELS item, or the newest video where nothing is marked", async () => {
    const marked = scripted(() => ({
      body: {
        data: [
          {
            id: "p1",
            media_type: "IMAGE",
            media_product_type: "FEED",
            permalink: "https://www.instagram.com/p/p1/",
            timestamp: "2026-09-28T10:00:00+0000",
          },
          {
            id: "v0",
            media_type: "VIDEO",
            media_product_type: "FEED",
            permalink: "https://www.instagram.com/p/v0/",
            timestamp: "2026-09-27T10:00:00+0000",
          },
          {
            id: "r1",
            media_type: "VIDEO",
            media_product_type: "REELS",
            permalink: "https://www.instagram.com/reel/r1/",
            timestamp: "2026-09-26T10:00:00+0000",
            caption: "boss",
            comments_count: 4,
          },
        ],
      },
    }));
    expect(await marked.client.latestReel(TOKEN)).toEqual({
      id: "r1",
      permalink: "https://www.instagram.com/reel/r1/",
      timestamp: "2026-09-26T10:00:00+0000",
      caption: "boss",
      commentsCount: 4,
    });
    expect(marked.asked[0]?.url.pathname).toBe("/v25.0/me/media");
    const unmarked = scripted(() => ({
      body: {
        data: [
          {
            id: "p1",
            media_type: "IMAGE",
            timestamp: "2026-09-28T10:00:00+0000",
          },
          {
            id: "v1",
            media_type: "VIDEO",
            permalink: "https://www.instagram.com/reel/v1/",
            timestamp: "2026-09-27T10:00:00+0000",
          },
          {
            id: "v2",
            media_type: "VIDEO",
            timestamp: "2026-09-26T10:00:00+0000",
          },
        ],
      },
    }));
    expect((await unmarked.client.latestReel(TOKEN))?.id).toBe("v1");
    const none = scripted(() => ({ body: { data: [] } }));
    expect(await none.client.latestReel(TOKEN)).toBeUndefined();
  });
  test("comments follow the cursor, and stop after four pages", async () => {
    const paged = scripted((url) => {
      const after = url.searchParams.get("after");
      return {
        body: {
          data: [
            {
              id: `c-${after ?? "first"}`,
              text: "x",
              username: "u",
              timestamp: "2026-09-27T18:00:00+0000",
              like_count: 1,
            },
          ],
          paging: { cursors: { after: `cursor-${after ?? "1"}` } },
        },
      };
    });
    const all = await paged.client.comments(TOKEN, "r1");
    expect(all).toHaveLength(COMMENT_PAGES);
    expect(paged.asked).toHaveLength(COMMENT_PAGES);
    expect(paged.asked[0]?.url.pathname).toBe("/v25.0/r1/comments");
    expect(paged.asked[0]?.url.searchParams.get("after")).toBeNull();
    expect(paged.asked[1]?.url.searchParams.get("after")).toBe("cursor-1");
    expect(paged.asked[0]?.url.searchParams.get("fields")).toBe(
      "id,text,username,timestamp,like_count",
    );
    const short = scripted(() => ({
      body: {
        data: [
          {
            id: "c1",
            text: "one",
            username: "u",
            timestamp: "t",
            like_count: 3,
          },
        ],
      },
    }));
    expect(await short.client.comments(TOKEN, "r1")).toEqual([
      { id: "c1", text: "one", username: "u", timestamp: "t", likeCount: 3 },
    ]);
    expect(short.asked).toHaveLength(1);
  });
  test("Meta's errors become InstagramError, and each is a sentence", async () => {
    const refused = scripted(() => ({
      status: 400,
      body: {
        error: {
          message: "Invalid OAuth access token - Cannot parse access token",
          type: "OAuthException",
          code: 190,
        },
      },
    }));
    const failure = await refused.client.me(TOKEN).catch((e: unknown) => e);
    expect(failure).toBeInstanceOf(InstagramError);
    expect((failure as InstagramError).code).toBe(190);
    expect(instagramSaid(failure)).toBe(
      "Instagram no longer accepts the token; connect the account again.",
    );
    const limited = scripted(() => ({
      status: 400,
      body: {
        error: { message: "Application request limit reached", code: 4 },
      },
    }));
    const other = await limited.client
      .latestReel(TOKEN)
      .catch((e: unknown) => e);
    expect(instagramSaid(other)).toBe(
      "Instagram answered: Application request limit reached.",
    );
    const silent = scripted(() => ({ status: 503, body: {} }));
    const down = await silent.client.me(TOKEN).catch((e: unknown) => e);
    expect(instagramSaid(down)).toBe(
      "Instagram answered: Instagram answered 503.",
    );
    expect(instagramSaid(new Error("boom"))).toBe("The run failed: boom.");
  });
  test("a refresh asks the refresh endpoint and answers with the new token", async () => {
    const { asked, client } = scripted(() => ({
      body: { access_token: FRESH, token_type: "bearer", expires_in: 5183944 },
    }));
    expect(await client.refresh(TOKEN)).toEqual({ token: FRESH });
    expect(asked[0]?.url.pathname).toBe("/refresh_access_token");
    expect(asked[0]?.url.searchParams.get("grant_type")).toBe(
      "ig_refresh_token",
    );
    expect(asked[0]?.url.searchParams.get("access_token")).toBe(TOKEN);
  });
});
/** An Instagram the test scripts, remembering every call and the token it saw. */
class FakeInstagram implements InstagramClient {
  readonly calls: { call: string; token: string }[] = [];
  username = "gamehandle";
  reel: Reel | undefined;
  /** What the Reel's comments are, whichever Reel is asked about. */
  replies: Comment[] = [];
  /** Thrown by the next calls while set. */
  failWith: Error | undefined;
  fresh = FRESH;
  private see(call: string, token: string): void {
    this.calls.push({ call, token });
    if (this.failWith !== undefined) throw this.failWith;
  }
  me(token: string): Promise<{ id: string; username: string }> {
    this.see("me", token);
    return Promise.resolve({
      id: "17841400000000000",
      username: this.username,
    });
  }
  latestReel(token: string): Promise<Reel | undefined> {
    this.see("reel", token);
    return Promise.resolve(this.reel);
  }
  comments(token: string, mediaId: string): Promise<Comment[]> {
    this.see(`comments:${mediaId}`, token);
    return Promise.resolve(this.replies);
  }
  refresh(token: string): Promise<{ token: string }> {
    this.see("refresh", token);
    return Promise.resolve({ token: this.fresh });
  }
  names(): string[] {
    return this.calls.map((c) => c.call);
  }
}
describe("prompts from Instagram", () => {
  let dataDir: string;
  let app: App;
  let servers: Servers;
  let alice: User;
  let bob: User;
  let repo: Repo;
  let routine: PromptRoutineHandle;
  let aliceCookie = "";
  let bobCookie = "";
  let adminToken = "";
  let rwToken = "";
  let bobToken = "";
  let sourceId = "";
  const instagram = new FakeInstagram();
  let clock = new Date("2026-09-28T14:59:00Z");
  const tick = (iso: string) => {
    clock = new Date(iso);
    return routine.runDue(clock);
  };
  const PROMPTS = "/api/v1/repos/alice/game/prompts";
  const SETTINGS = "/alice/game/settings/prompts";
  /** A browser's request to the forge: a cookie, and a same-origin form. */
  const web = (
    cookie: string,
    path: string,
    init: RequestInit & { form?: Record<string, string>; origin?: string } = {},
  ): Promise<Response> => {
    const headers = new Headers(init.headers);
    if (cookie !== "") headers.set("cookie", cookie);
    const method = init.form !== undefined ? "POST" : (init.method ?? "GET");
    if (init.form !== undefined)
      headers.set("origin", init.origin ?? new URL(servers.url).origin);
    return fetch(`${servers.url}${path}`, {
      ...init,
      method,
      headers,
      redirect: "manual",
      ...(init.form === undefined
        ? {}
        : { body: new URLSearchParams(init.form) }),
    });
  };
  const flashOf = (response: Response): string =>
    decodeURIComponent(response.headers.get("set-cookie") ?? "");
  const api = (
    path: string,
    init: RequestInit & { token?: string | null } = {},
  ) => {
    const headers = new Headers(init.headers);
    if (typeof init.body === "string")
      headers.set("content-type", "application/json");
    const token = init.token === undefined ? adminToken : init.token;
    if (token) headers.set("authorization", `Bearer ${token}`);
    return fetch(`${servers.url}${path}`, { ...init, headers });
  };
  const signIn = async (username: string): Promise<string> => {
    const response = await fetch(`${servers.url}/signin`, {
      method: "POST",
      body: new URLSearchParams({ username, password: "a-good-passphrase" }),
      redirect: "manual",
    });
    return `${(response.headers.get("set-cookie") ?? "").split(";")[0]!}; forge_mode=dev`;
  };
  const source = () => getPromptSource(app.db, sourceId)!;
  const openIssues = () => listIssues(app.db, repo.id, { limit: 50 });
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-prompts-"));
    app = createApp({ dataDir, port: 0 });
    servers = await serve(app);
    routine = startPromptRoutine(app, {
      client: instagram,
      now: () => clock,
      // The test drives the clock; the timer must never run on its own.
      everyMs: 3_600_000,
    });
    const a = await createUser(app.db, {
      username: "alice",
      email: "[email protected]",
      password: "a-good-passphrase",
      adminIfFirst: true,
    });
    if (!a.ok) throw new Error(a.error);
    alice = a.value;
    const b = await createUser(app.db, {
      username: "bob",
      email: "[email protected]",
      password: "a-good-passphrase",
    });
    if (!b.ok) throw new Error(b.error);
    bob = b.value;
    aliceCookie = await signIn("alice");
    bobCookie = await signIn("bob");
    adminToken = createToken(app.db, alice.id, "admin", "admin").token;
    rwToken = createToken(app.db, alice.id, "rw", "rw").token;
    bobToken = createToken(app.db, bob.id, "admin", "admin").token;
    const made = await createRepo(app, alice, {
      name: "game",
      visibility: "public",
      description: "A game with an audience",
    });
    if (!made.ok) throw new Error(String(made.error));
    repo = made.value;
    // A builder on the crew, so a tell has somebody to go to.
    const scout = await createAgent(app, alice, { username: "scout" });
    if (!scout.ok) throw new Error(String(scout.error));
    expect(addToCrew(app, alice, repo, "scout").ok).toBe(true);
  });
  afterAll(async () => {
    await routine.stop();
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("adding needs a daily HH:MM, and seals the token where nothing shows it again", async () => {
    for (const good of ["00:00", "09:30", "15:00", "23:59"])
      expect(`${good}: ${isDailyTime(good)}`).toBe(`${good}: true`);
    for (const bad of ["24:00", "9:00", "15:60", "15:00:00", "noon", ""])
      expect(`${bad}: ${isDailyTime(bad)}`).toBe(`${bad}: false`);
    const insert = (token: string, atUtc: string) =>
      addPromptSource(app.db, dataDir, {
        repoId: repo.id,
        kind: "instagram",
        token,
        atUtc,
      });
    expect(insert(TOKEN, "25:00")).toEqual({ ok: false, error: "invalid_at" });
    expect(insert("", "15:00")).toEqual({ ok: false, error: "invalid_token" });
    expect(insert("has a space", "15:00")).toEqual({
      ok: false,
      error: "invalid_token",
    });
    expect(listPromptSources(app.db, repo.id)).toEqual([]);
    // Through the API: the codes, then the item — without the token.
    const badAt = await api(PROMPTS, {
      method: "POST",
      body: JSON.stringify({ kind: "instagram", token: TOKEN, at: "24:00" }),
    });
    expect(badAt.status).toBe(422);
    expect(((await badAt.json()) as { error: string }).error).toBe(
      "invalid_at",
    );
    const badKind = await api(PROMPTS, {
      method: "POST",
      body: JSON.stringify({ kind: "tiktok", token: TOKEN, at: "15:00" }),
    });
    expect(((await badKind.json()) as { error: string }).error).toBe(
      "invalid_kind",
    );
    const added = await api(PROMPTS, {
      method: "POST",
      body: JSON.stringify({ kind: "instagram", token: TOKEN, at: "15:00" }),
    });
    expect(added.status).toBe(201);
    const text = await added.text();
    expect(text).not.toContain(TOKEN);
    const item = JSON.parse(text) as {
      id: string;
      kind: string;
      account: string;
      atUtc: string;
      lastRanAt: string | null;
      lastSaid: string;
      lastIssueNumber: number | null;
      tokenRefreshedAt: string;
    };
    expect(item).toEqual({
      id: item.id,
      kind: "instagram",
      account: "",
      atUtc: "15:00",
      lastRanAt: null,
      lastSaid: "",
      lastIssueNumber: null,
      tokenRefreshedAt: item.tokenRefreshedAt,
    });
    expect("token" in item).toBe(false);
    sourceId = item.id;
    // Sealed in the row, opened only by its own id, absent from every listing.
    const row = app.db
      .query<
        { token_enc: string },
        [string]
      >("SELECT token_enc FROM prompt_source WHERE id = ?1")
      .get(sourceId)!;
    expect(row.token_enc).not.toContain(TOKEN);
    expect(row.token_enc.startsWith("v1:")).toBe(true);
    expect(openPromptToken(app.db, dataDir, sourceId)).toEqual({
      ok: true,
      value: TOKEN,
    });
    expect(openPromptToken(app.db, dataDir, "nope")).toEqual({
      ok: false,
      error: "not_found",
    });
    expect(JSON.stringify(listPromptSources(app.db, repo.id))).not.toContain(
      TOKEN,
    );
    expect(await (await api(PROMPTS)).text()).not.toContain(TOKEN);
    expect(await (await web(aliceCookie, SETTINGS)).text()).not.toContain(
      TOKEN,
    );
    expect(source().createdBy).toBe(alice.id);
    // One account per repository.
    const again = await api(PROMPTS, {
      method: "POST",
      body: JSON.stringify({ kind: "instagram", token: TOKEN, at: "16:00" }),
    });
    expect(again.status).toBe(422);
    expect(((await again.json()) as { error: string }).error).toBe(
      "already_connected",
    );
  });
  test("nothing before the hour; once after it; not again the same day", async () => {
    instagram.reel = reelOf("reel-1", "2026-09-27");
    instagram.replies = [
      comment("c2", "first!!", 2, at("2026-09-27T18:01:00+0000"), "quick_one"),
      comment(
        "c1",
        "Add a boss fight at the end of level 3\nIt feels empty right now.",
        5,
        at("2026-09-27T18:05:00+0000"),
        "fan_one",
      ),
      comment("c3", "", 99, at("2026-09-27T18:00:00+0000"), "blank"),
    ];
    await tick("2026-09-28T14:59:00Z");
    expect(instagram.names()).toEqual([]);
    expect(source().lastRanAt).toBeNull();
    expect(openIssues()).toEqual([]);
    await tick("2026-09-28T15:00:00Z");
    expect(instagram.names()).toEqual(["me", "reel", "comments:reel-1"]);
    expect(instagram.calls.every((c) => c.token === TOKEN)).toBe(true);
    const ran = source();
    expect(ran.account).toBe("gamehandle");
    expect(ran.lastRanAt).toBe("2026-09-28T15:00:00.000Z");
    expect(ran.lastMediaId).toBe("reel-1");
    expect(ran.lastIssueNumber).toBe(1);
    expect(ran.lastSaid).toBe(
      'Told the crew #1: "Add a boss fight at the end of level 3" — @fan_one, 5 likes.',
    );
    // The tell: the comment's first line is the title, the rest and the
    // provenance are the body, and the builder has it.
    const issue = getIssue(app.db, repo.id, 1)!;
    expect(issue.title).toBe("Add a boss fight at the end of level 3");
    expect(issue.body).toBe(
      "Add a boss fight at the end of level 3\nIt feels empty right now.\n\nFrom Instagram: the top comment (5 likes) by @fan_one on the Reel of 2026-09-27. https://www.instagram.com/reel/reel-1/",
    );
    expect(issue.authorName).toBe("alice");
    expect(issue.assigneeName).toBe("scout");
    const told = listEvents(app.db, { repoId: repo.id, limit: 50 }).filter(
      (e) => e.kind === "prompt.told",
    );
    expect(told).toHaveLength(1);
    expect(told[0]?.payload).toEqual({
      source: sourceId,
      kind: "instagram",
      mediaId: "reel-1",
      commentId: "c1",
      issue: 1,
    });
    expect(told[0]?.actorId).toBeNull();
    // Later the same day: nothing more.
    await tick("2026-09-28T15:30:00Z");
    await tick("2026-09-28T23:59:00Z");
    expect(instagram.names()).toEqual(["me", "reel", "comments:reel-1"]);
    expect(source().lastRanAt).toBe("2026-09-28T15:00:00.000Z");
  });
  test("the same Reel is never told twice", async () => {
    instagram.calls.length = 0;
    await tick("2026-09-29T15:00:00Z");
    // The account is known, so `me` is not asked again; the Reel is known,
    // so its comments are not read.
    expect(instagram.names()).toEqual(["reel"]);
    expect(source().lastSaid).toBe(
      "No new Reel since 2026-09-27; the last one was told as #1.",
    );
    expect(source().lastRanAt).toBe("2026-09-29T15:00:00.000Z");
    expect(openIssues()).toHaveLength(1);
  });
  test("a Reel with no comments yet is looked at again tomorrow", async () => {
    instagram.calls.length = 0;
    instagram.reel = reelOf("reel-2", "2026-09-29");
    instagram.replies = [];
    await tick("2026-09-30T15:00:00Z");
    expect(instagram.names()).toEqual(["reel", "comments:reel-2"]);
    expect(source().lastSaid).toBe("The latest Reel has no comments yet.");
    expect(source().lastMediaId).toBe("reel-1");
    expect(source().lastIssueNumber).toBe(1);
    expect(openIssues()).toHaveLength(1);
    instagram.calls.length = 0;
    instagram.replies = [
      comment(
        "c9",
        "Make the jump feel heavier",
        1,
        at("2026-09-30T09:00:00+0000"),
        "ana",
      ),
    ];
    await tick("2026-10-01T15:00:00Z");
    expect(instagram.names()).toEqual(["reel", "comments:reel-2"]);
    expect(source().lastMediaId).toBe("reel-2");
    expect(source().lastIssueNumber).toBe(2);
    expect(source().lastSaid).toBe(
      'Told the crew #2: "Make the jump feel heavier" — @ana, 1 like.',
    );
    expect(getIssue(app.db, repo.id, 2)?.body).toContain(
      "the top comment (1 like) by @ana on the Reel of 2026-09-29.",
    );
  });
  test("no Reel at all is a sentence", async () => {
    instagram.reel = undefined;
    await tick("2026-10-02T15:00:00Z");
    expect(source().lastSaid).toBe("No Reel yet.");
    expect(source().lastMediaId).toBe("reel-2");
  });
  test("Instagram's refusals are sentences, never throws", async () => {
    instagram.failWith = new InstagramError(
      190,
      "Error validating access token: Session has expired",
      "OAuthException",
    );
    await tick("2026-10-03T15:00:00Z");
    expect(source().lastSaid).toBe(
      "Instagram no longer accepts the token; connect the account again.",
    );
    expect(source().lastRanAt).toBe("2026-10-03T15:00:00.000Z");
    instagram.failWith = new InstagramError(
      4,
      "Application request limit reached",
    );
    await tick("2026-10-04T15:00:00Z");
    expect(source().lastSaid).toBe(
      "Instagram answered: Application request limit reached.",
    );
    instagram.failWith = new Error("socket hang up");
    await tick("2026-10-05T15:00:00Z");
    expect(source().lastSaid).toBe("The run failed: socket hang up.");
    instagram.failWith = undefined;
    // Nothing above told anybody anything.
    expect(openIssues()).toHaveLength(2);
  });
  test("a token older than fifty days is refreshed, and the new one is what runs from then on", async () => {
    const before = source().tokenRefreshedAt;
    instagram.calls.length = 0;
    instagram.reel = reelOf("reel-3", "2026-11-19");
    instagram.replies = [
      comment("c20", "A hard mode", 8, at("2026-11-19T20:00:00+0000"), "vet"),
    ];
    // Pasted 2026-09-28; fifty-three days on.
    await tick("2026-11-20T15:00:00Z");
    expect(instagram.calls).toEqual([
      { call: "refresh", token: TOKEN },
      { call: "reel", token: FRESH },
      { call: "comments:reel-3", token: FRESH },
    ]);
    expect(source().tokenRefreshedAt).toBe("2026-11-20T15:00:00.000Z");
    expect(source().tokenRefreshedAt).not.toBe(before);
    expect(openPromptToken(app.db, dataDir, sourceId)).toEqual({
      ok: true,
      value: FRESH,
    });
    expect(source().lastIssueNumber).toBe(3);
    // The next day: fresh, no refresh.
    instagram.calls.length = 0;
    await tick("2026-11-21T15:00:00Z");
    expect(instagram.calls).toEqual([{ call: "reel", token: FRESH }]);
    // And the sealed row never held either token in the clear.
    const row = app.db
      .query<
        { token_enc: string },
        [string]
      >("SELECT token_enc FROM prompt_source WHERE id = ?1")
      .get(sourceId)!;
    expect(row.token_enc).not.toContain(FRESH);
    expect(row.token_enc).not.toContain(TOKEN);
  });
  test("Fetch now runs at once, whatever the hour, through the API", async () => {
    // Already ran today; a new Reel is up.
    instagram.calls.length = 0;
    instagram.reel = reelOf("reel-4", "2026-11-21");
    instagram.replies = [
      comment("c30", "Co-op please", 12, at("2026-11-21T12:00:00+0000"), "duo"),
    ];
    const ran = await api(`${PROMPTS}/${sourceId}/run`, { method: "POST" });
    expect(ran.status).toBe(200);
    const text = await ran.text();
    expect(text).not.toContain(FRESH);
    const item = JSON.parse(text) as {
      lastSaid: string;
      lastIssueNumber: number;
      account: string;
    };
    expect(item.lastSaid).toBe(
      'Told the crew #4: "Co-op please" — @duo, 12 likes.',
    );
    expect(item.lastIssueNumber).toBe(4);
    expect(item.account).toBe("gamehandle");
    expect(instagram.names()).toEqual(["reel", "comments:reel-4"]);
    expect(getIssue(app.db, repo.id, 4)?.title).toBe("Co-op please");
    const unknown = await api(`${PROMPTS}/nope/run`, { method: "POST" });
    expect(unknown.status).toBe(422);
    expect(((await unknown.json()) as { error: string }).error).toBe(
      "no_such_source",
    );
  });
  test("admin only, like the domains: scope, then admin over the repository", async () => {
    expect((await api(PROMPTS, { token: rwToken })).status).toBe(403);
    expect((await api(PROMPTS, { token: null })).status).toBe(401);
    expect((await api(PROMPTS, { token: bobToken })).status).toBe(404);
    expect(
      (
        await api(PROMPTS, {
          method: "POST",
          body: JSON.stringify({
            kind: "instagram",
            token: "stolen",
            at: "15:00",
          }),
          token: bobToken,
        })
      ).status,
    ).toBe(404);
    expect(
      (
        await api(`${PROMPTS}/${sourceId}/run`, {
          method: "POST",
          token: bobToken,
        })
      ).status,
    ).toBe(404);
    expect(
      (
        await api(`${PROMPTS}/${sourceId}/run`, {
          method: "POST",
          token: rwToken,
        })
      ).status,
    ).toBe(403);
    expect(
      (
        await api(`${PROMPTS}/${sourceId}`, {
          method: "DELETE",
          token: rwToken,
        })
      ).status,
    ).toBe(403);
    expect(
      (
        await api(`${PROMPTS}/${sourceId}`, {
          method: "DELETE",
          token: bobToken,
        })
      ).status,
    ).toBe(404);
    expect(getPromptSource(app.db, sourceId)).toBeDefined();
    // The pages: a non-admin meets the one 404; another origin, 403.
    expect((await web(bobCookie, SETTINGS)).status).toBe(404);
    expect((await web("", SETTINGS)).status).toBe(404);
    expect(
      (
        await web(bobCookie, SETTINGS, {
          form: { token: "stolen", at: "15:00" },
        })
      ).status,
    ).toBe(404);
    expect(
      (await web(bobCookie, `${SETTINGS}/${sourceId}/run`, { form: {} }))
        .status,
    ).toBe(404);
    expect(
      (await web(bobCookie, `${SETTINGS}/${sourceId}/delete`, { form: {} }))
        .status,
    ).toBe(404);
    expect(
      (
        await web(aliceCookie, `${SETTINGS}/${sourceId}/delete`, {
          form: {},
          origin: "https://evil.example",
        })
      ).status,
    ).toBe(403);
    expect(getPromptSource(app.db, sourceId)).toBeDefined();
    expect(listPromptSources(app.db, repo.id)).toHaveLength(1);
  });
  test("the settings page: the card, the steps, the doors", async () => {
    const page = words(await (await web(aliceCookie, SETTINGS)).text());
    expect(page).toContain(">Prompts<");
    expect(page).toContain("<h2>Instagram</h2>");
    expect(page).toContain("@gamehandle");
    expect(page).toContain("every day at 15:00 UTC");
    expect(page).toContain("Told the crew #4");
    expect(page).toContain("Token refreshed");
    expect(page).toContain("refreshes it again around 2027-01-09");
    expect(page).toContain("Fetch now");
    expect(page).toContain(`${SETTINGS}/${sourceId}/run`);
    expect(page).toContain(
      encodeURIComponent(`${SETTINGS}/${sourceId}/delete`),
    );
    expect(page).toContain("instagram_business_basic");
    expect(page).toContain("instagram_business_manage_comments");
    expect(page).toContain("Business Login for Instagram");
    expect(page).toContain("never shown again");
    expect(page).not.toContain(FRESH);
    expect(page).not.toContain(TOKEN);
    // The confirm page knows this door.
    const confirm = await web(
      aliceCookie,
      `/-/confirm?to=${encodeURIComponent(`${SETTINGS}/${sourceId}/delete`)}`,
    );
    expect(confirm.status).toBe(200);
    expect(await confirm.text()).toContain("Disconnect Instagram?");
    // Fetch now from the page flashes what the run said.
    instagram.calls.length = 0;
    const fetched = await web(aliceCookie, `${SETTINGS}/${sourceId}/run`, {
      form: {},
    });
    expect(fetched.status).toBe(303);
    expect(fetched.headers.get("location")).toBe(SETTINGS);
    expect(flashOf(fetched)).toContain(
      "No new Reel since 2026-11-21; the last one was told as #4.",
    );
    expect(instagram.names()).toEqual(["reel"]);
    // Remove, and the form is back.
    const removed = await web(aliceCookie, `${SETTINGS}/${sourceId}/delete`, {
      form: {},
    });
    expect(removed.status).toBe(303);
    expect(flashOf(removed)).toContain("Instagram is disconnected");
    expect(getPromptSource(app.db, sourceId)).toBeUndefined();
    const empty = words(await (await web(aliceCookie, SETTINGS)).text());
    expect(empty).toContain(
      "Once a day, the top comment on your latest Reel becomes the crew's next tell.",
    );
    expect(empty).toContain('type="password"');
    expect(empty).toContain('name="token"');
    expect(empty).toContain('type="time"');
    expect(empty).toContain('value="15:00"');
    expect(empty).not.toContain("Fetch now");
    const gone = await web(aliceCookie, `${SETTINGS}/${sourceId}/delete`, {
      form: {},
    });
    expect(flashOf(gone)).toContain("No account by that id");
    // Adding from the form, at another hour.
    const refused = await web(aliceCookie, SETTINGS, {
      form: { token: TOKEN, at: "9:00" },
    });
    expect(flashOf(refused)).toContain("hours and minutes in UTC");
    const added = await web(aliceCookie, SETTINGS, {
      form: { token: TOKEN, at: "09:30" },
    });
    expect(added.status).toBe(303);
    expect(flashOf(added)).toContain("Instagram is connected");
    expect(flashOf(added)).toContain("09:30 UTC");
    const fresh = words(await (await web(aliceCookie, SETTINGS)).text());
    expect(fresh).toContain("every day at 09:30 UTC");
    expect(fresh).toContain("not read yet");
    expect(fresh).toContain("Has not run yet.");
    expect(fresh).not.toContain(TOKEN);
    const events = listEvents(app.db, { repoId: repo.id, limit: 50 }).map(
      (e) => e.kind,
    );
    expect(events.filter((k) => k === "prompt.source_added")).toHaveLength(2);
    expect(events.filter((k) => k === "prompt.source_removed")).toHaveLength(1);
  });
  test("the API removes, and says so once", async () => {
    const listed = (await (await api(PROMPTS)).json()) as {
      items: { id: string; atUtc: string; account: string }[];
    };
    expect(listed.items).toHaveLength(1);
    expect(listed.items[0]?.atUtc).toBe("09:30");
    expect(listed.items[0]?.account).toBe("");
    const id = listed.items[0]!.id;
    const removed = await api(`${PROMPTS}/${id}`, { method: "DELETE" });
    expect(removed.status).toBe(200);
    expect(await removed.json()).toEqual({});
    expect(
      ((await (await api(PROMPTS)).json()) as { items: unknown[] }).items,
    ).toEqual([]);
    const again = await api(`${PROMPTS}/${id}`, { method: "DELETE" });
    expect(again.status).toBe(422);
    expect(((await again.json()) as { error: string }).error).toBe(
      "no_such_source",
    );
    // A run now finds nothing due, and asks Instagram nothing.
    instagram.calls.length = 0;
    await tick("2026-11-22T15:00:00Z");
    expect(instagram.names()).toEqual([]);
  });
  test("a tell nobody can take is said honestly: opened, not told", async () => {
    const made = await api(PROMPTS, {
      method: "POST",
      body: JSON.stringify({ kind: "instagram", token: TOKEN, at: "15:00" }),
    });
    expect(made.status).toBe(201);
    sourceId = ((await made.json()) as { id: string }).id;
    expect(removeFromCrew(app, alice, repo, "scout").ok).toBe(true);
    instagram.failWith = undefined;
    instagram.reel = reelOf("reel-7", "2026-10-09");
    instagram.replies = [
      comment("c7", "Let us pet the dog", 8, at("2026-10-09T18:00:00+0000"), "dogfan"),
    ];
    clock = new Date("2026-10-10T15:00:00Z");
    const before = openIssues().length;
    await routine.runNow(sourceId);
    const issue = openIssues().find((i) => i.title === "Let us pet the dog")!;
    expect(issue).toBeDefined();
    expect(issue.assigneeName).toBeNull();
    expect(openIssues()).toHaveLength(before + 1);
    expect(source().lastSaid).toBe(
      `Opened #${issue.number}: "Let us pet the dog" — @dogfan, 8 likes; nobody on the crew to take it yet.`,
    );
    expect(addToCrew(app, alice, repo, "scout").ok).toBe(true);
  });
  test("a sentence about an error never carries the token, even when Instagram's words quote the request", async () => {
    instagram.failWith = new InstagramError(
      400,
      `Bad request to https://graph.instagram.com/v25.0/me/media?fields=id&access_token=${TOKEN}`,
    );
    clock = new Date("2026-10-11T15:00:00Z");
    await routine.runNow(sourceId);
    const said = source().lastSaid;
    expect(said).toContain("Instagram answered:");
    expect(said).not.toContain(TOKEN);
    expect(await (await api(PROMPTS)).text()).not.toContain(TOKEN);
    expect(await (await web(aliceCookie, SETTINGS)).text()).not.toContain(TOKEN);
    // A plain failure that quotes it, the same.
    instagram.failWith = new Error(`socket closed while sending ${TOKEN}`);
    await routine.runNow(sourceId);
    expect(source().lastSaid).not.toContain(TOKEN);
    instagram.failWith = undefined;
  });
  test("a run claims its row before any network work: two sweeps over one row tell the crew once", async () => {
    // A second routine over the same database — two forges over one data
    // directory, or a timer started twice — with a slow Instagram.
    let release: (() => void) | undefined;
    const slow = new FakeInstagram();
    slow.reel = reelOf("reel-8", "2026-10-11");
    slow.replies = [
      comment("c8", "Add a secret door", 6, at("2026-10-11T18:00:00+0000"), "sneak"),
    ];
    const slowReel = slow.latestReel.bind(slow);
    slow.latestReel = async (token) => {
      await new Promise<void>((resolve) => {
        release = resolve;
      });
      return slowReel(token);
    };
    instagram.reel = slow.reel;
    instagram.replies = slow.replies;
    const other = startPromptRoutine(app, {
      client: slow,
      now: () => clock,
      everyMs: 3_600_000,
    });
    clock = new Date("2026-10-12T15:00:00Z");
    const before = openIssues().length;
    const a = other.runDue(clock);
    const b = routine.runDue(clock);
    await Bun.sleep(20);
    release?.();
    await Promise.all([a, b]);
    await other.stop();
    expect(openIssues()).toHaveLength(before + 1);
    expect(source().lastMediaId).toBe("reel-8");
    // Only one of the two ever spoke to Instagram.
    expect([slow.names().length > 0, instagram.names().some((n) => n === "comments:reel-8")].filter(Boolean)).toHaveLength(1);
    // The claim itself, in the open: once a day, unless a person insists.
    expect(claimPromptRun(app.db, sourceId, clock)).toBe(false);
    expect(claimPromptRun(app.db, sourceId, clock, { force: true })).toBe(true);
  });
  test("stop waits for a run in flight, but not forever", async () => {
    let hang: (() => void) | undefined;
    const stuck: InstagramClient = {
      me: (t) => instagram.me(t),
      refresh: (t) => instagram.refresh(t),
      comments: (t, id) => instagram.comments(t, id),
      latestReel: () =>
        new Promise<Reel | undefined>((resolve) => {
          hang = () => resolve(undefined);
        }),
    };
    const other = startPromptRoutine(app, {
      client: stuck,
      now: () => clock,
      everyMs: 3_600_000,
      stopDeadlineMs: 50,
    });
    const running = other.runNow(sourceId);
    const began = Date.now();
    await other.stop();
    expect(Date.now() - began).toBeLessThan(2_000);
    hang?.();
    await running;
  });
});
		@@ -713,6 +713,74 @@ is resting and why, with a button to use it again sooner. Nothing granted
713	713	anywhere means the forge's own token, as before. Every run remembers the
714	714	account it spent.
715	715
	716	### Prompts from Instagram
	717
	718	A repository's next tell can come from its audience. Under Settings →
	719	Prompts an admin connects the Instagram account of the app — a game with
	720	an account of its own, say — and once a day the forge reads the account's
	721	latest Reel, takes its most-liked top-level comment, and tells the crew
	722	exactly as a person would from the studio box: an issue is opened and
	723	routed to a builder. The comment is the tell; the forge invents nothing.
	724
	725	What happens at the hour, every day, in UTC:
	726
	727	1. The token is refreshed when it is more than fifty days old (below).
	728	2. The account's username is read once, the first time, and shown.
	729	3. The latest Reel is found — the newest item Instagram marks `REELS`, or
	730	the newest video where it marks nothing.
	731	4. Its top-level comments are read, at most four pages of fifty. The top
	732	comment is the one with the most likes; a tie goes to the earliest. A
	733	comment with no text does not count.
	734	5. The crew is told, and the Reel is remembered as told.
	735
	736	The tell has one shape. Its first line is the issue's title, as with any
	737	tell, and the rest is its body:
	738
	739	```
	740	<the comment, as written>
	741
	742	From Instagram: the top comment (<n> likes) by @<username> on the Reel of <YYYY-MM-DD>. <permalink>
	743	```
	744
	745	Nothing is told twice, and nothing is told early. A Reel already told is
	746	skipped ("No new Reel since <date>; the last one was told as #<n>."), a
	747	Reel with no comments yet is left for tomorrow and _not_ remembered as told
	748	("The latest Reel has no comments yet."), and an account with no Reel says
	749	so ("No Reel yet."). Every run leaves its sentence on the settings page, and
	750	Fetch now runs the same routine at once, whatever the hour. A run that
	751	meets an error ends in a sentence too, never a throw: Instagram's own words
	752	in one line, or — for a token Instagram no longer accepts — "connect the
	753	account again". A repository whose routine ran today does not run again
	754	until tomorrow, and one whose forge was down at the hour catches up on the
	755	next tick.
	756
	757	The token is a long-lived Instagram user token, which lives sixty days. It
	758	is sealed under the forge's key, bound to its row, opened only for the run,
	759	and never listed or shown again; the API's listing carries the account, the
	760	hour, and what the last run said, and nothing else. When it is more than
	761	fifty days old the forge refreshes it — Instagram allows a refresh once a
	762	token is a day old — stores the new one sealed, and notes the time, so a
	763	token pasted once stays good for as long as the account does. A token the
	764	forge cannot open (a data directory restored under another key) asks to be
	765	connected again, like everything else about a lost key.
	766
	767	The one-time steps at Meta, none of which needs App Review for an account
	768	of your own:
	769
	770	1. Make the Instagram account a professional one (Business or Creator).
	771	2. At developers.facebook.com, make a Meta app and add the Instagram
	772	product with Business Login for Instagram. No Facebook Page is needed.
	773	3. Get a token for the account with the scopes `instagram_business_basic`
	774	and `instagram_business_manage_comments`.
	775	4. Exchange it for a long-lived token, the one that lives sixty days.
	776	5. Paste it under Settings → Prompts, choose the hour, and press Add — or
	777	`POST /api/v1/repos/:owner/:name/prompts` with
	778	`{ "kind": "instagram", "token": "…", "at": "15:00" }`.
	779
	780	`prompt.told` on the outbox names the source, the Reel, the comment and the
	781	issue; it is for the repository's admins, like everything else about its
	782	settings.
	783
716	784	## Configuration
717	785
718	786	\| variable \| default \| meaning \|
		@@ -0,0 +1,152 @@
	1	/**
	2	* Prompt-source actions: connect the Instagram account whose Reels prompt
	3	* the crew, look at it now, and disconnect it. Admin over the repository,
	4	* like every other setting that spends the crew's time. The daily run
	5	* itself is the routine's (`crew/prompts.ts`); `Fetch now` borrows it.
	6	*/
	7
	8	import type { App } from "../app.ts";
	9	import {
	10	addPromptSource as insertSource,
	11	getPromptSource,
	12	listPromptSources as querySources,
	13	removePromptSource as deleteSource,
	14	type AddPromptError,
	15	type PromptKind,
	16	type PromptSource,
	17	} from "../core/prompts.ts";
	18	import type { Repo } from "../core/repos.ts";
	19	import type { User } from "../core/users.ts";
	20	import { promptsFor } from "../crew/prompts.ts";
	21	import { err, ok, type Result } from "../kernel/result.ts";
	22	import { requireRepoAdmin } from "./access.ts";
	23
	24	/** A source as a page or the API shows it: everything but the token. */
	25	export interface PromptSourceView {
	26	readonly id: string;
	27	readonly kind: PromptKind;
	28	/** The account's username, or empty until the first run has asked. */
	29	readonly account: string;
	30	readonly atUtc: string;
	31	readonly lastRanAt: string \| null;
	32	readonly lastSaid: string;
	33	readonly lastIssueNumber: number \| null;
	34	readonly tokenRefreshedAt: string;
	35	}
	36
	37	export const viewOf = (source: PromptSource): PromptSourceView => ({
	38	id: source.id,
	39	kind: source.kind,
	40	account: source.account,
	41	atUtc: source.atUtc,
	42	lastRanAt: source.lastRanAt,
	43	lastSaid: source.lastSaid,
	44	lastIssueNumber: source.lastIssueNumber,
	45	tokenRefreshedAt: source.tokenRefreshedAt,
	46	});
	47
	48	export type PromptError = "not_found" \| "no_such_source";
	49
	50	/** One of this repository's sources, by id — never another's. */
	51	function ownedSource(
	52	app: App,
	53	repo: Repo,
	54	sourceId: string,
	55	): PromptSource \| undefined {
	56	const source = getPromptSource(app.db, sourceId);
	57	return source?.repoId === repo.id ? source : undefined;
	58	}
	59
	60	export function listPromptSources(
	61	app: App,
	62	actor: User \| undefined,
	63	repo: Repo,
	64	): Result<PromptSourceView[], "not_found"> {
	65	const admin = requireRepoAdmin(app, actor, repo);
	66	if (!admin.ok) return admin;
	67	return ok(querySources(app.db, repo.id).map(viewOf));
	68	}
	69
	70	export interface AddPromptInput {
	71	readonly kind: string;
	72	readonly token: string;
	73	readonly at: string;
	74	}
	75
	76	/**
	77	* Connect an account. One of each kind per repository: a second Instagram
	78	* account would mean two tells a day from two places, and the page shows
	79	* one. The token is sealed on the way in and not shown again.
	80	*/
	81	export function addPromptSource(
	82	app: App,
	83	actor: User \| undefined,
	84	repo: Repo,
	85	input: AddPromptInput,
	86	): Result<
	87	PromptSourceView,
	88	"not_found" \| "invalid_kind" \| "already_connected" \| AddPromptError
	89	> {
	90	const admin = requireRepoAdmin(app, actor, repo);
	91	if (!admin.ok) return admin;
	92	if (input.kind !== "instagram") return err("invalid_kind");
	93	if (querySources(app.db, repo.id).some((s) => s.kind === input.kind))
	94	return err("already_connected");
	95	const added = insertSource(app.db, app.config.dataDir, {
	96	repoId: repo.id,
	97	kind: input.kind,
	98	token: input.token,
	99	atUtc: input.at,
	100	createdBy: admin.value.id,
	101	});
	102	if (!added.ok) return added;
	103	app.bus.append({
	104	kind: "prompt.source_added",
	105	repoId: repo.id,
	106	actorId: admin.value.id,
	107	payload: {
	108	source: added.value.id,
	109	kind: added.value.kind,
	110	at: added.value.atUtc,
	111	},
	112	});
	113	return ok(viewOf(added.value));
	114	}
	115
	116	/** Look at Instagram now, whatever the hour; the source as the run left it. */
	117	export async function runPromptSource(
	118	app: App,
	119	actor: User \| undefined,
	120	repo: Repo,
	121	sourceId: string,
	122	): Promise<Result<PromptSourceView, PromptError \| "not_running">> {
	123	const admin = requireRepoAdmin(app, actor, repo);
	124	if (!admin.ok) return admin;
	125	if (ownedSource(app, repo, sourceId) === undefined)
	126	return err("no_such_source");
	127	const routine = promptsFor(app);
	128	if (routine === undefined) return err("not_running");
	129	const ran = await routine.runNow(sourceId);
	130	return ran === undefined ? err("no_such_source") : ok(viewOf(ran));
	131	}
	132
	133	/** Disconnect. The token is forgotten; the issues already told stay. */
	134	export function removePromptSource(
	135	app: App,
	136	actor: User \| undefined,
	137	repo: Repo,
	138	sourceId: string,
	139	): Result<void, PromptError> {
	140	const admin = requireRepoAdmin(app, actor, repo);
	141	if (!admin.ok) return admin;
	142	const source = ownedSource(app, repo, sourceId);
	143	if (source === undefined \|\| !deleteSource(app.db, source.id))
	144	return err("no_such_source");
	145	app.bus.append({
	146	kind: "prompt.source_removed",
	147	repoId: repo.id,
	148	actorId: admin.value.id,
	149	payload: { source: source.id, kind: source.kind, account: source.account },
	150	});
	151	return ok();
	152	}
		@@ -26,6 +26,7 @@ export function eventAudience(kind: string): EventAudience {
26	26	kind.startsWith("webhook.") \|\|
27	27	kind.startsWith("app.env_") \|\|
28	28	kind.startsWith("app.domain.") \|\|
	29	kind.startsWith("prompt.") \|\|
29	30	kind === "repo.settings_updated"
30	31	)
31	32	return "admins";
		@@ -0,0 +1,271 @@
	1	/**
	2	* Prompt sources: where a repository's next tell comes from when nobody is
	3	* typing. One kind so far — an Instagram account whose latest Reel's top
	4	* comment becomes the crew's next tell, once a day (docs/APPS.md, "Prompts
	5	* from Instagram").
	6	*
	7	* The token is sealed at rest under the forge's key, bound to the row it
	8	* belongs to, and opened only for the run; nothing here ever returns it in
	9	* a listing. Pure data: no Instagram, no authz, no events — the routine in
	10	* `crew/prompts.ts` does the asking, and `actions/prompts.ts` the deciding.
	11	*/
	12
	13	import type { Database } from "bun:sqlite";
	14	import { id } from "../kernel/id.ts";
	15	import { err, ok, type Result } from "../kernel/result.ts";
	16	import { open, seal, type OpenError } from "../kernel/secret.ts";
	17
	18	export type PromptKind = "instagram";
	19
	20	export interface PromptSource {
	21	readonly id: string;
	22	readonly repoId: string;
	23	readonly kind: PromptKind;
	24	/** The account's username, learnt on the first run; empty until then. */
	25	readonly account: string;
	26	/** When the routine runs each day, `HH:MM` in UTC. */
	27	readonly atUtc: string;
	28	/** When the sealed token was pasted or last refreshed. */
	29	readonly tokenRefreshedAt: string;
	30	readonly createdBy: string \| null;
	31	readonly createdAt: string;
	32	readonly lastRanAt: string \| null;
	33	/** What the last run said, one sentence for a person. */
	34	readonly lastSaid: string;
	35	/** The Reel already told about, so the same one is never told twice. */
	36	readonly lastMediaId: string \| null;
	37	readonly lastIssueNumber: number \| null;
	38	}
	39
	40	interface Row {
	41	id: string;
	42	repo_id: string;
	43	kind: string;
	44	account: string;
	45	at_utc: string;
	46	token_refreshed_at: string;
	47	created_by: string \| null;
	48	created_at: string;
	49	last_ran_at: string \| null;
	50	last_said: string;
	51	last_media_id: string \| null;
	52	last_issue_number: number \| null;
	53	}
	54
	55	/** Every column but the sealed token: what a listing may carry. */
	56	const COLUMNS = `id, repo_id, kind, account, at_utc, token_refreshed_at, created_by,
	57	created_at, last_ran_at, last_said, last_media_id, last_issue_number`;
	58
	59	const toSource = (r: Row): PromptSource => ({
	60	id: r.id,
	61	repoId: r.repo_id,
	62	kind: "instagram",
	63	account: r.account,
	64	atUtc: r.at_utc,
	65	tokenRefreshedAt: r.token_refreshed_at,
	66	createdBy: r.created_by,
	67	createdAt: r.created_at,
	68	lastRanAt: r.last_ran_at,
	69	lastSaid: r.last_said,
	70	lastMediaId: r.last_media_id,
	71	lastIssueNumber: r.last_issue_number,
	72	});
	73
	74	const aad = (sourceId: string): string => `prompt-source:${sourceId}`;
	75
	76	const TOKEN_MAX = 1024;
	77
	78	export type AddPromptError = "invalid_at" \| "invalid_token";
	79
	80	/** `HH:MM`, twenty-four hours, both parts zero-padded. */
	81	export function isDailyTime(at: string): boolean {
	82	return /^(?:[01]\d\|2[0-3]):[0-5]\d$/.test(at);
	83	}
	84
	85	/**
	86	* A token as Instagram hands one out: printable, no spaces, not absurdly
	87	* long. Its shape is otherwise Instagram's business; the first run finds
	88	* out whether it is accepted, and says so.
	89	*/
	90	export function isPromptToken(token: string): boolean {
	91	return (
	92	token.length > 0 &&
	93	token.length <= TOKEN_MAX &&
	94	/^[\x21-\x7e]+$/.test(token)
	95	);
	96	}
	97
	98	export function addPromptSource(
	99	db: Database,
	100	dataDir: string,
	101	input: {
	102	repoId: string;
	103	kind: PromptKind;
	104	token: string;
	105	atUtc: string;
	106	createdBy?: string \| undefined;
	107	now?: Date \| undefined;
	108	},
	109	): Result<PromptSource, AddPromptError> {
	110	const atUtc = input.atUtc.trim();
	111	if (!isDailyTime(atUtc)) return err("invalid_at");
	112	const token = input.token.trim();
	113	if (!isPromptToken(token)) return err("invalid_token");
	114	const sourceId = id();
	115	const at = (input.now ?? new Date()).toISOString();
	116	db.query(
	117	`INSERT INTO prompt_source (id, repo_id, kind, token_enc, token_refreshed_at, at_utc, created_by, created_at)
	118	VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?5)`,
	119	).run(
	120	sourceId,
	121	input.repoId,
	122	input.kind,
	123	seal(dataDir, token, aad(sourceId)),
	124	at,
	125	atUtc,
	126	input.createdBy ?? null,
	127	);
	128	return ok(getPromptSource(db, sourceId)!);
	129	}
	130
	131	export function getPromptSource(
	132	db: Database,
	133	sourceId: string,
	134	): PromptSource \| undefined {
	135	const row = db
	136	.query<Row, [string]>(`SELECT ${COLUMNS} FROM prompt_source WHERE id = ?1`)
	137	.get(sourceId);
	138	return row ? toSource(row) : undefined;
	139	}
	140
	141	/** A repository's sources, oldest first. */
	142	export function listPromptSources(
	143	db: Database,
	144	repoId: string,
	145	): PromptSource[] {
	146	return db
	147	.query<
	148	Row,
	149	[string]
	150	>(`SELECT ${COLUMNS} FROM prompt_source WHERE repo_id = ?1 ORDER BY created_at, id`)
	151	.all(repoId)
	152	.map(toSource);
	153	}
	154
	155	/**
	156	* The sources whose time has come today: `at_utc` at or before the clock's
	157	* `HH:MM`, and no run yet on the clock's date. A forge that was down at the
	158	* hour catches up on its next tick; one that ran already waits for tomorrow.
	159	*/
	160	export function duePromptSources(db: Database, now: Date): PromptSource[] {
	161	const iso = now.toISOString();
	162	return db
	163	.query<Row, [string, string]>(
	164	`SELECT ${COLUMNS} FROM prompt_source
	165	WHERE at_utc <= ?1 AND (last_ran_at IS NULL OR substr(last_ran_at, 1, 10) <> ?2)
	166	ORDER BY at_utc, created_at, id`,
	167	)
	168	.all(iso.slice(11, 16), iso.slice(0, 10))
	169	.map(toSource);
	170	}
	171
	172	/**
	173	* Claim a source for a run, atomically: the row's `last_ran_at` moves to now
	174	* only if it has not run today — or unconditionally for a person's "Fetch
	175	* now". False means another run has it; the caller does nothing more.
	176	*/
	177	export function claimPromptRun(
	178	db: Database,
	179	sourceId: string,
	180	now: Date,
	181	o: { force?: boolean \| undefined } = {},
	182	): boolean {
	183	const iso = now.toISOString();
	184	const result = db
	185	.query(
	186	`UPDATE prompt_source SET last_ran_at = ?2
	187	WHERE id = ?1
	188	AND (?3 = 1 OR last_ran_at IS NULL OR substr(last_ran_at, 1, 10) <> substr(?2, 1, 10))`,
	189	)
	190	.run(sourceId, iso, o.force ? 1 : 0);
	191	return result.changes === 1;
	192	}
	193
	194	/** The token, for a run. A value that will not open says so, never a throw. */
	195	export function openPromptToken(
	196	db: Database,
	197	dataDir: string,
	198	sourceId: string,
	199	): Result<string, "not_found" \| OpenError> {
	200	const row = db
	201	.query<
	202	{ token_enc: string },
	203	[string]
	204	>("SELECT token_enc FROM prompt_source WHERE id = ?1")
	205	.get(sourceId);
	206	if (!row) return err("not_found");
	207	return open(dataDir, row.token_enc, aad(sourceId));
	208	}
	209
	210	/** After a refresh: the new token sealed, and the moment noted. */
	211	export function storePromptToken(
	212	db: Database,
	213	dataDir: string,
	214	sourceId: string,
	215	token: string,
	216	now: Date,
	217	): void {
	218	db.query(
	219	"UPDATE prompt_source SET token_enc = ?2, token_refreshed_at = ?3 WHERE id = ?1",
	220	).run(sourceId, seal(dataDir, token, aad(sourceId)), now.toISOString());
	221	}
	222
	223	export function setPromptAccount(
	224	db: Database,
	225	sourceId: string,
	226	username: string,
	227	): void {
	228	db.query("UPDATE prompt_source SET account = ?2 WHERE id = ?1").run(
	229	sourceId,
	230	username,
	231	);
	232	}
	233
	234	/**
	235	* What a run came to. The media id and the issue number are written only
	236	* when a Reel was actually told — a Reel with no comments yet leaves them
	237	* alone, so tomorrow's run looks at the same Reel again.
	238	*/
	239	export function recordPromptRun(
	240	db: Database,
	241	sourceId: string,
	242	run: {
	243	said: string;
	244	mediaId?: string \| undefined;
	245	issueNumber?: number \| undefined;
	246	now: Date;
	247	},
	248	): PromptSource \| undefined {
	249	db.query(
	250	`UPDATE prompt_source
	251	SET last_ran_at = ?2,
	252	last_said = ?3,
	253	last_media_id = COALESCE(?4, last_media_id),
	254	last_issue_number = COALESCE(?5, last_issue_number)
	255	WHERE id = ?1`,
	256	).run(
	257	sourceId,
	258	run.now.toISOString(),
	259	run.said.slice(0, 400),
	260	run.mediaId ?? null,
	261	run.issueNumber ?? null,
	262	);
	263	return getPromptSource(db, sourceId);
	264	}
	265
	266	export function removePromptSource(db: Database, sourceId: string): boolean {
	267	return (
	268	db.query("DELETE FROM prompt_source WHERE id = ?1").run(sourceId).changes >
	269	0
	270	);
	271	}
		@@ -898,4 +898,28 @@ export const migrations: readonly string[] = [
898	898	);
899	899	CREATE INDEX app_domain_app ON app_domain(app_id);
900	900	`,
	901
	902	// 33 — where a repository's next tell comes from when nobody is typing:
	903	// an Instagram account whose latest Reel's top comment becomes the crew's
	904	// next tell, once a day at `at_utc`. The token is sealed under the forge's
	905	// key, bound to the row; `last_media_id` is the Reel already told, so the
	906	// same one is never told twice; `last_said` is the last run's sentence.
	907	`
	908	CREATE TABLE prompt_source (
	909	id TEXT PRIMARY KEY,
	910	repo_id TEXT NOT NULL REFERENCES repo(id) ON DELETE CASCADE,
	911	kind TEXT NOT NULL,
	912	account TEXT NOT NULL DEFAULT '',
	913	token_enc TEXT NOT NULL,
	914	token_refreshed_at TEXT NOT NULL,
	915	at_utc TEXT NOT NULL,
	916	created_by TEXT REFERENCES user(id) ON DELETE SET NULL,
	917	created_at TEXT NOT NULL,
	918	last_ran_at TEXT,
	919	last_said TEXT NOT NULL DEFAULT '',
	920	last_media_id TEXT,
	921	last_issue_number INTEGER
	922	);
	923	CREATE INDEX prompt_source_repo ON prompt_source(repo_id);
	924	`,
901	925	];
		@@ -0,0 +1,244 @@
	1	/**
	2	* Instagram, as the prompt routine sees it: who the token belongs to, the
	3	* newest Reel, its top-level comments, and a fresh token. The Instagram API
	4	* with Instagram Login (Meta's "Business Login for Instagram"): a
	5	* professional account, a long-lived user token, no Facebook Page.
	6	*
	7	* The interface is what the routine is written against; `graphInstagram`
	8	* is the one that talks to Meta, and a test hands the routine a fake. The
	9	* token travels only in the query string of a request to Meta's host, as
	10	* the API asks, and is never logged or put in a sentence.
	11	*/
	12
	13	import { redactSecrets } from "../kernel/log.ts";
	14
	15	/** A Reel, or the newest video when the API does not say which are Reels. */
	16	export interface Reel {
	17	readonly id: string;
	18	readonly permalink: string;
	19	/** As Instagram gives it, ISO 8601. */
	20	readonly timestamp: string;
	21	readonly caption: string;
	22	readonly commentsCount: number;
	23	}
	24
	25	/** A top-level comment. */
	26	export interface Comment {
	27	readonly id: string;
	28	readonly text: string;
	29	readonly username: string;
	30	readonly timestamp: string;
	31	readonly likeCount: number;
	32	}
	33
	34	export interface InstagramClient {
	35	me(token: string): Promise<{ id: string; username: string }>;
	36	latestReel(token: string): Promise<Reel \| undefined>;
	37	comments(token: string, mediaId: string): Promise<Comment[]>;
	38	refresh(token: string): Promise<{ token: string }>;
	39	}
	40
	41	/**
	42	* What Meta answered with instead of data. `code` is Meta's: 190 is a
	43	* token that is invalid or has expired, the one a person must act on.
	44	*/
	45	export class InstagramError extends Error {
	46	constructor(
	47	readonly code: number,
	48	message: string,
	49	readonly type = "",
	50	) {
	51	super(message);
	52	this.name = "InstagramError";
	53	}
	54	}
	55
	56	/** The token is no good: the person who pasted it must make another. */
	57	export const TOKEN_REFUSED = 190;
	58
	59	/**
	60	* One sentence for a run that met an error, for the source's `last_said`.
	61	* Never the token, never a stack.
	62	*/
	63	export function instagramSaid(error: unknown): string {
	64	if (error instanceof InstagramError) {
	65	if (error.code === TOKEN_REFUSED)
	66	return "Instagram no longer accepts the token; connect the account again.";
	67	return `Instagram answered: ${oneSentence(redactSecrets(error.message))}`;
	68	}
	69	if (error instanceof Error && error.name === "TimeoutError")
	70	return "Instagram did not answer within ten seconds.";
	71	return `The run failed: ${oneSentence(redactSecrets(error instanceof Error ? error.message : String(error)))}`;
	72	}
	73
	74	function oneSentence(text: string): string {
	75	const line = text.replace(/\s+/g, " ").trim();
	76	const cut = line.length > 200 ? `${line.slice(0, 199).trimEnd()}…` : line;
	77	return /[.!?…]$/.test(cut) ? cut : `${cut}.`;
	78	}
	79
	80	/**
	81	* The comment that becomes the tell: the most liked, and of those the
	82	* earliest. A comment with nothing in it is nobody's prompt.
	83	*/
	84	export function topComment(comments: readonly Comment[]): Comment \| undefined {
	85	let top: Comment \| undefined;
	86	for (const comment of comments) {
	87	if (comment.text.trim() === "") continue;
	88	if (
	89	top === undefined \|\|
	90	comment.likeCount > top.likeCount \|\|
	91	(comment.likeCount === top.likeCount && comment.timestamp < top.timestamp)
	92	)
	93	top = comment;
	94	}
	95	return top;
	96	}
	97
	98	// ---- the real one ----
	99
	100	const HOST = "https://graph.instagram.com";
	101	const VERSION = "v25.0";
	102	const TIMEOUT_MS = 10_000;
	103	/** How many pages of comments are read before the top is taken as found. */
	104	export const COMMENT_PAGES = 4;
	105	const COMMENTS_PER_PAGE = 50;
	106	const MEDIA_PER_PAGE = 50;
	107
	108	type Json = Record<string, unknown>;
	109
	110	interface MediaItem {
	111	id?: unknown;
	112	media_type?: unknown;
	113	media_product_type?: unknown;
	114	permalink?: unknown;
	115	timestamp?: unknown;
	116	caption?: unknown;
	117	comments_count?: unknown;
	118	}
	119
	120	interface CommentItem {
	121	id?: unknown;
	122	text?: unknown;
	123	username?: unknown;
	124	timestamp?: unknown;
	125	like_count?: unknown;
	126	}
	127
	128	const str = (v: unknown): string => (typeof v === "string" ? v : "");
	129	const num = (v: unknown): number => (typeof v === "number" ? v : 0);
	130
	131	export function graphInstagram(fetchFn: typeof fetch = fetch): InstagramClient {
	132	const get = async (
	133	path: string,
	134	params: Record<string, string>,
	135	): Promise<Json> => {
	136	const url = new URL(path, HOST);
	137	for (const [key, value] of Object.entries(params))
	138	url.searchParams.set(key, value);
	139	const response = await fetchFn(url, {
	140	signal: AbortSignal.timeout(TIMEOUT_MS),
	141	headers: { accept: "application/json" },
	142	});
	143	const body = (await response.json().catch(() => ({}))) as Json;
	144	const failure = body["error"];
	145	if (typeof failure === "object" && failure !== null) {
	146	const e = failure as Json;
	147	throw new InstagramError(
	148	num(e["code"]),
	149	str(e["message"]) \|\| `Instagram answered ${response.status}`,
	150	str(e["type"]),
	151	);
	152	}
	153	if (!response.ok)
	154	throw new InstagramError(
	155	response.status,
	156	`Instagram answered ${response.status}`,
	157	);
	158	return body;
	159	};
	160
	161	const items = <T>(body: Json): T[] =>
	162	Array.isArray(body["data"]) ? (body["data"] as T[]) : [];
	163	const after = (body: Json): string \| undefined => {
	164	const paging = body["paging"];
	165	if (typeof paging !== "object" \|\| paging === null) return undefined;
	166	const cursors = (paging as Json)["cursors"];
	167	if (typeof cursors !== "object" \|\| cursors === null) return undefined;
	168	const cursor = str((cursors as Json)["after"]);
	169	return cursor === "" ? undefined : cursor;
	170	};
	171
	172	return {
	173	async me(token) {
	174	const body = await get(`/${VERSION}/me`, {
	175	fields: "id,username",
	176	access_token: token,
	177	});
	178	return { id: str(body["id"]), username: str(body["username"]) };
	179	},
	180
	181	async latestReel(token) {
	182	const body = await get(`/${VERSION}/me/media`, {
	183	fields:
	184	"id,media_type,media_product_type,permalink,timestamp,caption,comments_count",
	185	limit: String(MEDIA_PER_PAGE),
	186	access_token: token,
	187	});
	188	const media = items<MediaItem>(body);
	189	// Newest first. Where the API says which items are Reels, that is
	190	// the answer; where it does not (Instagram Login may leave the field
	191	// out), the newest video stands in.
	192	const says = media.some((m) => typeof m.media_product_type === "string");
	193	const found = says
	194	? media.find((m) => m.media_product_type === "REELS")
	195	: media.find((m) => m.media_type === "VIDEO");
	196	if (found === undefined \|\| str(found.id) === "") return undefined;
	197	return {
	198	id: str(found.id),
	199	permalink: str(found.permalink),
	200	timestamp: str(found.timestamp),
	201	caption: str(found.caption),
	202	commentsCount: num(found.comments_count),
	203	};
	204	},
	205
	206	async comments(token, mediaId) {
	207	const out: Comment[] = [];
	208	let cursor: string \| undefined;
	209	for (let page = 0; page < COMMENT_PAGES; page++) {
	210	const body = await get(
	211	`/${VERSION}/${encodeURIComponent(mediaId)}/comments`,
	212	{
	213	fields: "id,text,username,timestamp,like_count",
	214	limit: String(COMMENTS_PER_PAGE),
	215	access_token: token,
	216	...(cursor === undefined ? {} : { after: cursor }),
	217	},
	218	);
	219	for (const c of items<CommentItem>(body))
	220	out.push({
	221	id: str(c.id),
	222	text: str(c.text),
	223	username: str(c.username),
	224	timestamp: str(c.timestamp),
	225	likeCount: num(c.like_count),
	226	});
	227	cursor = after(body);
	228	if (cursor === undefined) break;
	229	}
	230	return out;
	231	},
	232
	233	async refresh(token) {
	234	const body = await get("/refresh_access_token", {
	235	grant_type: "ig_refresh_token",
	236	access_token: token,
	237	});
	238	const fresh = str(body["access_token"]);
	239	if (fresh === "")
	240	throw new InstagramError(0, "the refresh answered with no token");
	241	return { token: fresh };
	242	},
	243	};
	244	}
		@@ -0,0 +1,265 @@
	1	/**
	2	* The prompt routine: once a day, for every repository that asked, the top
	3	* comment on the account's latest Reel becomes the crew's next tell
	4	* (docs/APPS.md, "Prompts from Instagram").
	5	*
	6	* Every minute the clock is compared with each source's hour; a source
	7	* whose hour has passed and that has not run today runs. A run reads the
	8	* latest Reel, takes its most-liked comment, and tells the crew as a
	9	* person would from the studio box — `tellCrew` opens the issue and routes
	10	* it. Nothing is invented: no Reel, no new Reel, or no comment yet is a
	11	* sentence on the settings page and another look tomorrow. One source runs
	12	* at a time, `Fetch now` included, and a run that fails is a sentence too,
	13	* never a throw into the timer.
	14	*/
	15
	16	import type { App } from "../app.ts";
	17	import { tellCrew } from "../actions/crew.ts";
	18	import {
	19	duePromptSources,
	20	getPromptSource,
	21	openPromptToken,
	22	recordPromptRun,
	23	setPromptAccount,
	24	storePromptToken,
	25	type PromptSource,
	26	claimPromptRun,
	27	} from "../core/prompts.ts";
	28	import { getRepoById } from "../core/repos.ts";
	29	import { getUserById } from "../core/users.ts";
	30	import { createLog, redactSecrets } from "../kernel/log.ts";
	31	import {
	32	instagramSaid,
	33	topComment,
	34	type Comment,
	35	type InstagramClient,
	36	type Reel,
	37	} from "./instagram.ts";
	38
	39	const log = createLog("prompts");
	40
	41	/** How often the clock is looked at. */
	42	/** How long a shutdown waits for a run in flight before going on without it. */
	43	const STOP_DEADLINE_MS = 15_000;
	44	const TICK_MS = 60_000;
	45
	46	/**
	47	* A long-lived token lives sixty days and may be refreshed once it is a day
	48	* old; at fifty the forge refreshes it, leaving a ten-day margin for a
	49	* forge that is down.
	50	*/
	51	export const REFRESH_AFTER_DAYS = 50;
	52	const DAY_MS = 24 * 3_600_000;
	53
	54	export interface PromptRoutineOptions {
	55	readonly client: InstagramClient;
	56	/** The clock, for tests. @default the wall clock */
	57	readonly now?: (() => Date) \| undefined;
	58	/** @default a minute */
	59	readonly everyMs?: number \| undefined;
	60	/** How long `stop()` waits for a run in flight. */
	61	readonly stopDeadlineMs?: number \| undefined;
	62	}
	63
	64	export interface PromptRoutineHandle {
	65	/** Stop the clock; a run in flight finishes first. */
	66	readonly stop: () => Promise<void>;
	67	/** Run every source whose hour has come and that has not run today. */
	68	readonly runDue: (now?: Date) => Promise<void>;
	69	/** Run one source now, whatever the hour; the source after, or nothing for an unknown id. */
	70	readonly runNow: (sourceId: string) => Promise<PromptSource \| undefined>;
	71	}
	72
	73	const handles = new WeakMap<App, PromptRoutineHandle>();
	74
	75	/** The routine of this forge, if one was started. */
	76	export const promptsFor = (app: App): PromptRoutineHandle \| undefined =>
	77	handles.get(app);
	78
	79	export function startPromptRoutine(
	80	app: App,
	81	options: PromptRoutineOptions,
	82	): PromptRoutineHandle {
	83	const now = options.now ?? (() => new Date());
	84	let stopped = false;
	85	// One source at a time: the due sweep and a `Fetch now` join the same
	86	// line, so a run never overlaps another on the same row.
	87	let line: Promise<unknown> = Promise.resolve();
	88	const enqueue = <T>(work: () => Promise<T>): Promise<T> => {
	89	const next = line.then(work);
	90	line = next.catch(() => undefined);
	91	return next;
	92	};
	93
	94	const runDue = (at = now()): Promise<void> =>
	95	enqueue(async () => {
	96	for (const source of duePromptSources(app.db, at)) {
	97	if (stopped) return;
	98	await runSource(app, options.client, source, at);
	99	}
	100	});
	101
	102	const timer = setInterval(() => {
	103	if (stopped) return;
	104	runDue().catch((error) =>
	105	log.error("prompt sweep failed", { error: String(error) }),
	106	);
	107	}, options.everyMs ?? TICK_MS);
	108
	109	const handle: PromptRoutineHandle = {
	110	runDue,
	111	runNow: (sourceId) =>
	112	enqueue(async () => {
	113	const source = getPromptSource(app.db, sourceId);
	114	if (source === undefined) return undefined;
	115	return runSource(app, options.client, source, now(), true);
	116	}),
	117	stop: async () => {
	118	stopped = true;
	119	clearInterval(timer);
	120	// A run in flight is waited for, but not forever: shutdown has its
	121	// own patience, and Instagram is not allowed to spend it.
	122	await Promise.race([
	123	line,
	124	Bun.sleep(options.stopDeadlineMs ?? STOP_DEADLINE_MS),
	125	]);
	126	if (handles.get(app) === handle) handles.delete(app);
	127	},
	128	};
	129	handles.set(app, handle);
	130	return handle;
	131	}
	132
	133	/** The likes, in words. */
	134	const likes = (n: number): string => (n === 1 ? "1 like" : `${n} likes`);
	135
	136	/** The Reel's day, as `YYYY-MM-DD`, from Instagram's timestamp. */
	137	const dayOf = (reel: Reel): string => reel.timestamp.slice(0, 10);
	138
	139	/** What the settings page shows of a told comment: its first line, shortly. */
	140	function shortly(text: string): string {
	141	const line = text.trim().split(/\n/)[0]!.trim();
	142	return line.length <= 60 ? line : `${line.slice(0, 60).trimEnd()}…`;
	143	}
	144
	145	/**
	146	* The tell, as the crew reads it: the comment itself first — `tellCrew`
	147	* makes its first line the title — and where it came from beneath.
	148	*/
	149	export function tellText(reel: Reel, comment: Comment): string {
	150	return `${comment.text.trim()}\n\nFrom Instagram: the top comment (${likes(comment.likeCount)}) by @${comment.username} on the Reel of ${dayOf(reel)}. ${reel.permalink}`.trim();
	151	}
	152
	153	/**
	154	* One run of one source. Every exit is a sentence recorded on the row; the
	155	* media id is recorded only when the Reel was told, so a Reel that has no
	156	* comments yet is looked at again tomorrow.
	157	*/
	158	async function runSource(
	159	app: App,
	160	client: InstagramClient,
	161	source: PromptSource,
	162	now: Date,
	163	/** A person's "Fetch now" runs whatever the day; the sweep does not. */
	164	force = false,
	165	): Promise<PromptSource \| undefined> {
	166	// Every token this run has held. A sentence about an error may quote a
	167	// request, and a request carries the token: nothing recorded — and so
	168	// nothing listed or shown — may hold it, or anything shaped like one.
	169	const tokens: string[] = [];
	170	const clean = (said: string): string =>
	171	redactSecrets(
	172	tokens.reduce((text, t) => (t === "" ? text : text.split(t).join("[token]")), said),
	173	);
	174	const record = (run: {
	175	said: string;
	176	mediaId?: string;
	177	issueNumber?: number;
	178	}) => recordPromptRun(app.db, source.id, { ...run, said: clean(run.said), now });
	179	// The row is claimed before any network work: two forges over one data
	180	// directory, or two ticks over one row, must not tell the crew twice.
	181	if (!claimPromptRun(app.db, source.id, now, { force })) return undefined;
	182	try {
	183	const opened = openPromptToken(app.db, app.config.dataDir, source.id);
	184	if (!opened.ok)
	185	return record({
	186	said:
	187	opened.error === "not_found"
	188	? "The source is gone."
	189	: "The token would not open; connect the account again.",
	190	});
	191	let token = opened.value;
	192	tokens.push(token);
	193
	194	if (
	195	now.getTime() - Date.parse(source.tokenRefreshedAt) >
	196	REFRESH_AFTER_DAYS * DAY_MS
	197	) {
	198	const fresh = await client.refresh(token);
	199	storePromptToken(app.db, app.config.dataDir, source.id, fresh.token, now);
	200	token = fresh.token;
	201	tokens.push(token);
	202	}
	203
	204	if (source.account === "") {
	205	const me = await client.me(token);
	206	if (me.username !== "") setPromptAccount(app.db, source.id, me.username);
	207	}
	208
	209	const reel = await client.latestReel(token);
	210	if (reel === undefined) return record({ said: "No Reel yet." });
	211	if (reel.id === source.lastMediaId)
	212	return record({
	213	said:
	214	source.lastIssueNumber === null
	215	? `No new Reel since ${dayOf(reel)}.`
	216	: `No new Reel since ${dayOf(reel)}; the last one was told as #${source.lastIssueNumber}.`,
	217	});
	218
	219	const top = topComment(await client.comments(token, reel.id));
	220	if (top === undefined)
	221	return record({ said: "The latest Reel has no comments yet." });
	222
	223	const repo = getRepoById(app.db, source.repoId);
	224	if (repo === undefined) return record({ said: "The repository is gone." });
	225	const creator =
	226	source.createdBy === null
	227	? undefined
	228	: getUserById(app.db, source.createdBy);
	229	const told = await tellCrew(app, creator, repo, tellText(reel, top));
	230	if (!told.ok)
	231	return record({
	232	said:
	233	told.error === "unauthorized"
	234	? "The person who connected the account is gone; connect it again."
	235	: `The crew could not be told (${told.error}).`,
	236	});
	237
	238	const number = told.value.issue.number;
	239	app.bus.append({
	240	kind: "prompt.told",
	241	repoId: repo.id,
	242	payload: {
	243	source: source.id,
	244	kind: source.kind,
	245	mediaId: reel.id,
	246	commentId: top.id,
	247	issue: number,
	248	},
	249	});
	250	const who = `"${shortly(top.text)}" — @${top.username}, ${likes(top.likeCount)}`;
	251	return record({
	252	// Honest about who heard it: an issue opens with nobody to route it
	253	// to when the crew is empty, and that is not "told the crew".
	254	said:
	255	told.value.routed === undefined
	256	? `Opened #${number}: ${who}; nobody on the crew to take it yet.`
	257	: `Told the crew #${number}: ${who}.`,
	258	mediaId: reel.id,
	259	issueNumber: number,
	260	});
	261	} catch (error) {
	262	log.warn("prompt run failed", { source: source.id, error: String(error) });
	263	return record({ said: instagramSaid(error) });
	264	}
	265	}
		@@ -69,6 +69,12 @@ export function eventVerb(event: ForgeEvent): string {
69	69	if (kind === "app.domain.verified") return `verified the domain ${which}`;
70	70	return `removed the domain ${which}`;
71	71	}
	72	if (kind === "prompt.told") {
	73	const issue = payload["issue"];
	74	return typeof issue === "number"
	75	? `told the crew the top Instagram comment as #${issue}`
	76	: "told the crew the top Instagram comment";
	77	}
72	78	return WORDS[kind] ?? "acted on this repository";
73	79	}
74	80
		@@ -78,7 +84,9 @@ export function eventActor(
78	84	actorName: string \| undefined,
79	85	): string {
80	86	if (actorName !== undefined) return actorName;
81		return event.kind.startsWith("run.") \|\| event.kind.startsWith("app.")
	87	return event.kind.startsWith("run.") \|\|
	88	event.kind.startsWith("app.") \|\|
	89	event.kind.startsWith("prompt.")
82	90	? "the forge"
83	91	: "someone";
84	92	}
		@@ -120,4 +128,6 @@ const WORDS: Record<string, string> = {
120	128	"app.created": "made it an app",
121	129	"app.updated": "changed the app's settings",
122	130	"app.deleted": "stopped serving it as an app",
	131	"prompt.source_added": "connected an Instagram account to prompt the crew",
	132	"prompt.source_removed": "disconnected the Instagram account",
123	133	};
		@@ -159,6 +159,12 @@ import {
159	159	listAppDomains,
160	160	removeAppDomain,
161	161	} from "../actions/domains.ts";
	162	import {
	163	addPromptSource,
	164	listPromptSources,
	165	removePromptSource,
	166	runPromptSource,
	167	} from "../actions/prompts.ts";
162	168	import { listDomains } from "../core/domains.ts";
163	169	import type { Database } from "bun:sqlite";
164	170	import {
		@@ -2912,6 +2918,68 @@ export function apiRoutes(router: Router<Handler>): void {
2912	2918	},
2913	2919	);
2914	2920
	2921	// Where the crew's next tell comes from when nobody is typing
	2922	// (docs/APPS.md, "Prompts from Instagram"). Admin scope and admin over
	2923	// the repository; the token goes in once and never comes back out.
	2924	router.add("GET", "/api/v1/repos/:owner/:name/prompts", (ctx) => {
	2925	const denied = requireScope(ctx, "admin");
	2926	if (denied) return denied;
	2927	const repo = loadRepo(ctx);
	2928	if (!repo) return notFound();
	2929	const listed = listPromptSources(ctx.app, ctx.auth.user, repo);
	2930	if (!listed.ok) return respondAccess(listed.error, 422);
	2931	return json({ items: listed.value, next_cursor: null });
	2932	});
	2933
	2934	router.add("POST", "/api/v1/repos/:owner/:name/prompts", async (ctx) => {
	2935	const denied = requireScope(ctx, "admin");
	2936	if (denied) return denied;
	2937	const repo = loadRepo(ctx);
	2938	if (!repo) return notFound();
	2939	const input = await body(ctx.request);
	2940	const added = addPromptSource(ctx.app, ctx.auth.user, repo, {
	2941	kind: str(input.kind),
	2942	token: str(input.token),
	2943	at: str(input.at),
	2944	});
	2945	if (!added.ok) return respondAccess(added.error, 422);
	2946	return json(added.value, 201);
	2947	});
	2948
	2949	router.add(
	2950	"POST",
	2951	"/api/v1/repos/:owner/:name/prompts/:id/run",
	2952	async (ctx) => {
	2953	const denied = requireScope(ctx, "admin");
	2954	if (denied) return denied;
	2955	const repo = loadRepo(ctx);
	2956	if (!repo) return notFound();
	2957	const ran = await runPromptSource(
	2958	ctx.app,
	2959	ctx.auth.user,
	2960	repo,
	2961	ctx.params.id ?? "",
	2962	);
	2963	if (!ran.ok) return respondAccess(ran.error, 422);
	2964	return json(ran.value);
	2965	},
	2966	);
	2967
	2968	router.add("DELETE", "/api/v1/repos/:owner/:name/prompts/:id", (ctx) => {
	2969	const denied = requireScope(ctx, "admin");
	2970	if (denied) return denied;
	2971	const repo = loadRepo(ctx);
	2972	if (!repo) return notFound();
	2973	const removed = removePromptSource(
	2974	ctx.app,
	2975	ctx.auth.user,
	2976	repo,
	2977	ctx.params.id ?? "",
	2978	);
	2979	if (!removed.ok) return respondAccess(removed.error, 422);
	2980	return json({}, 200);
	2981	});
	2982
2915	2983	// The app's environment: names in, names out, and never a value back.
2916	2984	// `:var`, not `:name` — `:name` is the repository's.
2917	2985	router.add("GET", "/api/v1/repos/:owner/:name/app/env", (ctx) => {
		@@ -180,6 +180,10 @@ import {
180	180	labelDelete,
181	181	labelUpdate,
182	182	labelsPage,
	183	promptSourceAdd,
	184	promptSourceDelete,
	185	promptSourceRun,
	186	promptsSettingsPage,
183	187	repoDelete,
184	188	settingsPage,
185	189	settingsUpdate,
		@@ -809,6 +813,14 @@ export function buildRouter(): Router<Handler> {
809	813	"/:owner/:name/settings/app/domains/:host/delete",
810	814	appDomainDelete,
811	815	);
	816	router.add("GET", "/:owner/:name/settings/prompts", promptsSettingsPage);
	817	router.add("POST", "/:owner/:name/settings/prompts", promptSourceAdd);
	818	router.add("POST", "/:owner/:name/settings/prompts/:id/run", promptSourceRun);
	819	router.add(
	820	"POST",
	821	"/:owner/:name/settings/prompts/:id/delete",
	822	promptSourceDelete,
	823	);
812	824	router.add("GET", "/:owner/:name/settings/crew", crewSettingsPage);
813	825	router.add("POST", "/:owner/:name/settings/crew", crewAdd);
814	826	router.add(