Change a component and trace allowed and denied requests

npm ci
npx vitest run scripts/guide-actions.test.ts
npx vitest run scripts/starter.test.ts

function requireNoteId(value: unknown): string {
  if (typeof value !== 'string' || value === '')
    throw new Error('this row shows no note');
  return value;
}

export const ArchiveInputSchema = z.strictObject({
  noteId: z.string().min(1).max(32),
});
export const ArchiveOutputSchema = z.strictObject({
  noteId: z.string().min(1).max(32),
  archivedAt: z.number().int().nonnegative(),
});

{
  id: 'note-actions',
  component: 'Row',
  children: ['row-read', 'row-archive'],
},
{
  id: 'row-read',
  component: 'ActionButton',
  child: 'row-read-label',
},
{
  id: 'row-read-label',
  component: 'Line',
  kind: 'body',
  text: 'Mark read',
},
{
  id: 'row-archive',
  component: 'ActionButton',
  child: 'row-archive-label',
},
{
  id: 'row-archive-label',
  component: 'Line',
  kind: 'body',
  text: 'Archive',
},

attach: (view) => {
  view.watchById(
    'row-archive',
    ActionButton,
    (handle) =>
      void handle.bindAction('activate', actions.archiveNote, {
        subject: () => handle.read('id'),
      }),
  );
  view.watchById(
    'row-read',
    ActionButton,
    (handle) => void handle.bindAction('activate', actions.markRead),
  );
},

const markRead = Action.local<ActionButtonActivation>('mark-read')
  .input((event) => ({ noteId: requireNoteId(event.read('id')) }))
  .run(({ params }) => environment.recordRead(params.noteId))
  .build();

const archiveNote = Action.server<ActionButtonActivation, CallToolResult>(
  'archive-note',
  environment.transport,
)
  .input((event) => ({
    noteId: requireNoteId(event.read('id')),
    at: event.dataPath,
  }))
  // Inside the event turn: the application's hold on this row, owned by the invocation. The
  // scope gives it back when the invocation ends unless the success hook hands it over.
  .atActivation(({ scope, event }) =>
    scope.own(
      environment.holds.begin(requireNoteId(event.read('id'))),
      (token) => environment.holds.end(token),
    ),
  )
  .before(requireSession)
  .run(async ({ params, call }) => {
    const reply = await call(ARCHIVE_TOOL, { noteId: params.noteId });
    // A returned tool-level failure is a result, not an exception. Only a refusal the server marked
    // as having no effect is a known outcome; any other failure (a backend exception, an output the
    // server could not validate after writing) may follow an applied archive, so it stays unknown.
    if (declaresNoEffect(reply))
      throw new ArchiveDeclined('The server declined to archive the note');
    if (reply.isError === true) throw new Error('The archive request failed');
    return ArchiveOutputSchema.parse(reply.structuredContent);
  })

async ({ noteId }, ctx: ServerContext): Promise<CallToolResult> => {
  // Authorization is decided here, for this request, from the verified context alone.
  const identity = identityOf(ctx.http?.authInfo);
  if (!identity) return refusal(TEXT.signInRequired);
  try {
    const archived = await bounded(ctx, (signal) =>
      backend.archive(identity.accountId, noteId, signal),
    );
    // One sentence for an absent note, someone else's note and an archived one: nothing is disclosed.
    if (archived === undefined) return refusal(TEXT.cannotArchive);
    const output = ArchiveOutputSchema.parse({
      noteId,
      archivedAt: archived.archivedAt,
    });
    return {
      content: [{ type: 'text', text: 'archived' }],
      structuredContent: output,
    };
  } catch {
    // An exception, a wait that ran out of time, or an output that failed validation after the
    // write: the archive may have been applied (or may still be), so this failure does not claim otherwise.
    return failure(TEXT.unavailable);
  }
},

export function createSessionPrerequisite(
  transport: ServerTransport<CallToolResult>,
) {
  return prerequisite('session', async ({ signal }) => {
    const reply = await transport.callServerTool(
      { name: SESSION_TOOL, arguments: {} },
      { signal },
    );
    return reply.isError === true
      ? refuse('sign-in-required')
      : proceed({ signedIn: true as const });
  });
}

/** Cross-cutting requirement: the person confirms. A refusal means the handler never starts. */
export const confirmArchive = (
  environment: GuardEnvironment,
): Prerequisite<NoValues, unknown, Pressed> =>
  prerequisite('confirm', async ({ params, signal }) =>
    (await environment.confirm(params.noteId, signal))
      ? proceed()
      : refuse('not-confirmed'),

/** Cross-cutting requirement: a durable audit entry exists before the protected request is sent. */
export const auditArchive = (
  environment: GuardEnvironment,
): Prerequisite<{ readonly auditId: string }, unknown, Pressed> =>
  prerequisite('audit', async ({ params, signal }) => {
    try {
      return proceed({ auditId: await environment.record(params, signal) });
    } catch {
      return refuse('audit-unavailable'); // no audit entry, no protected request
    }
  });

return Action.server<InstanceEvent<unknown>, Reply>(
  'archive-note-guarded',
  transport,
)
  .input((event) => ({
    noteId: String(event.read('id')),
    at: event.dataPath,
  }))
  .before(requireSession) // 1. a valid session (its own request, counted apart)
  .before(confirmArchive(environment)) // 2. the person confirms
  .before(auditArchive(environment)) // 3. the audit entry exists
  .run(async ({ params, call }) => {
    const reply = await call('archive_note', { noteId: params.noteId });
    if (reply.isError === true) throw new Error('The archive request failed');
    return parseArchived(reply); // a reply is not an acknowledgement until the application has validated it
  })

.onSuccess(({ params, result, activation, current }) => {
  // The server confirmed: the hold now belongs to the application's owner for good.
  activation.transfer((token) => environment.holds.confirm(token));
  if (current())
    environment.present(params.at, `Archived at ${result.archivedAt}`);
})
.onFailure((context) => {
  if (context.stage === 'input') return; // nothing was read from the event, so no row can be named
  if (!context.current()) return; // the row shows another note now, or is gone
  if (context.stage === 'prerequisites') {
    // The handler never started: no archive request was sent.
    const { failure } = context;
    environment.present(
      context.params.at,
      `Not archived: ${failure.kind === 'refused' ? failure.reason : failure.kind}`,
    );
  } else if (
    context.failure.kind === 'handler-error' &&
    context.failure.error instanceof ArchiveDeclined
  ) {
    environment.present(
      context.params.at,
      'The server declined; nothing changed',
    );
  } else {
    // A timeout, a transport failure or an unreadable reply: the request may have been applied.
    environment.present(context.params.at, 'Archive status unknown');
  }
})
.onCanceled((context) => {
  if (!context.current()) return;
  environment.present(
    context.params.at,
    context.stage === 'prerequisites'
      ? 'Not archived: canceled'
      : 'Archive status unknown',
  );
})

view.watchById(
  'row-archive',
  ActionButton,
  (handle) =>
    void handle.bindAction('activate', actions.archiveNote, {
      subject: () => handle.read('id'),
    }),

begin(noteId: string): number {
  const token = (this.#next += 1);
  this.#tokens.set(token, { noteId, phase: 'pending' });
  this.#publish();
  return token;
}

/** Takes the token over for good: the invocation no longer releases it. */
confirm(token: number): void {
  const entry = this.#tokens.get(token);
  if (entry) entry.phase = 'confirmed';
  this.#publish();
}

/** Gives an unconfirmed token back. A confirmed token, or one already given back, is left alone. */
end(token: number): void {
  if (this.#tokens.get(token)?.phase === 'pending')
    this.#tokens.delete(token);
  this.#publish();
}

attach: (view) => {
  view.watchById(
    'row-archive',
    ActionButton,
    (handle) =>
      void handle.bindAction('activate', actions.archiveNote, {
        subject: () => handle.read('id'),
      }),
  );
  view.watchById(
    'row-read',
    ActionButton,
    (handle) => void handle.bindAction('activate', actions.markRead),
  );
},