@pulsarinteractive/geniusfitness 0.1.0-beta.1

package/src/commands.mjs

@@ -0,0 +1,271 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as z from 'zod/v4';
+import catalog from './command-catalog.mjs';
+import { CredentialStore } from './store.mjs';
+import { AgentError, fail, safeError } from './errors.mjs';
+
+export const operationIdSchema = z
+  .string()
+  .regex(/^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$/);
+const identifier = z
+  .string()
+  .min(1)
+  .max(128)
+  // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
+  .regex(/^[^\u0000-\u001f]+$/u);
+export const commandSchema = z
+  .object({
+    operationId: operationIdSchema,
+    issuedAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    scope: z
+      .string()
+      .max(256)
+      // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
+      .regex(/^(project|personal):[^\u0000-\u001f]+$/u),
+    epoch: identifier,
+    id: identifier,
+    expectedRevision: z
+      .string()
+      .regex(/^[1-9][0-9]{0,15}$/)
+      .nullable(),
+    kind: z.enum(Object.keys(catalog.commands)),
+    data: z.record(z.string(), z.json()),
+  })
+  .strict();
+export const draftSchema = commandSchema.omit({ operationId: true, issuedAt: true });
+const canonical = (value) =>
+  JSON.stringify(value, (_, item) =>
+    item && typeof item === 'object' && !Array.isArray(item)
+      ? Object.fromEntries(
+          Object.keys(item)
+            .sort()
+            .map((key) => [key, item[key]]),
+        )
+      : item,
+  );
+const checked = (schema, value) => {
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) {
+    fail(
+      'invalid_arguments',
+      'The command does not match its schema. Use commands describe; do not supply credentials or server-owned fields.',
+    );
+  }
+  return parsed.data;
+};
+/** Validate the public envelope, generated field allowlist and resource scope. */
+export function validateCommand(value) {
+  const command = checked(commandSchema, value),
+    definition = catalog.commands[command.kind];
+  if (
+    Buffer.byteLength(JSON.stringify(command)) > catalog.maxCommandBytes ||
+    Object.keys(command.data).some((key) => !definition.fields.includes(key)) ||
+    (definition.create ? command.expectedRevision !== null : command.expectedRevision === null)
+  ) {
+    fail(
+      'invalid_arguments',
+      'Use the declared command fields and size limit. Creation requires a null revision; other commands require the current record revision.',
+    );
+  }
+  const prefix = definition.module.startsWith('LocalUser/') ? 'personal:' : 'project:';
+  if (
+    !command.scope.startsWith(prefix) ||
+    (definition.module.endsWith('/$') && command.id !== command.scope.slice(prefix.length))
+  ) {
+    fail('invalid_arguments', 'The command must target the matching program or personal scope.');
+  }
+  if (
+    command.kind === 'program.create' &&
+    (!/^[a-f\d]{8}-[a-f\d]{4}-4[a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/i.test(command.id) ||
+      command.epoch !== command.id)
+  ) {
+    fail(
+      'invalid_arguments',
+      'Create a program with a UUID v4 as id, the same initial epoch, and scope project:<id>. Include title and icon.',
+    );
+  }
+  return command;
+}
+export function describeCommands() {
+  return {
+    ...catalog,
+    envelope: z.toJSONSchema(commandSchema),
+    draft: z.toJSONSchema(draftSchema),
+    recovery:
+      'Retain operationId, issuedAt and the complete body. Retry an uncertain write unchanged; reread before creating a new edit after a conflict.',
+  };
+}
+/** Read one bounded regular JSON file, rejecting symlinks and non-file inputs. */
+export async function readCommandFile(path) {
+  if (typeof path !== 'string') {
+    fail('invalid_arguments', 'Supply --file with a JSON command or draft.');
+  }
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > catalog.maxCommandBytes) {
+      fail(
+        'invalid_arguments',
+        `Use a regular JSON file no larger than ${catalog.maxCommandBytes} bytes.`,
+      );
+    }
+    const bytes = Buffer.alloc(catalog.maxCommandBytes + 1),
+      result = await handle.read(bytes, 0, bytes.length, 0);
+    if (result.bytesRead > catalog.maxCommandBytes) {
+      fail('invalid_arguments', `Command file exceeds ${catalog.maxCommandBytes} bytes.`);
+    }
+    return JSON.parse(bytes.subarray(0, result.bytesRead).toString('utf8'));
+  } catch (error) {
+    if (error instanceof AgentError) {
+      throw error;
+    }
+    fail('invalid_arguments', 'Could not read a regular, valid JSON command file.');
+  } finally {
+    await handle?.close();
+  }
+}
+const binding = (session) => ({
+  origin: session.origin,
+  connectionId: session.connection_id,
+  profileId: session.profile_id,
+  sessionId: session.session_id,
+});
+const receiptSchema = z
+  .object({
+    operationId: operationIdSchema,
+    scope: z.string(),
+    kind: z.string(),
+    epoch: z.string(),
+    cursor: z.string(),
+    items: z.array(
+      z
+        .object({
+          id: z.string(),
+          revision: z.string(),
+          collection: z.string(),
+          deleted: z.boolean(),
+        })
+        .strict(),
+    ),
+    affectedCollections: z.array(z.string()),
+  })
+  .strict();
+
+/** A journal is bound to one authenticated terminal identity. Persist the full
+ * request before the network call, never regenerate a UUID after a timeout.
+ * It contains private project text but no access/refresh tokens. A process crash
+ * leaves its operation lock for explicit recovery after all clients stop. */
+export class CommandJournal {
+  constructor(client) {
+    this.client = client;
+  }
+  store(id) {
+    checked(operationIdSchema, id);
+    return new CredentialStore({
+      directory: join(this.client.store.directory, 'operations', this.client.store.context),
+      context: id,
+      maxBytes: 524288,
+    });
+  }
+  async prepare(draft) {
+    const input = validateCommand({
+      ...checked(draftSchema, draft),
+      operationId: randomUUID(),
+      issuedAt: Date.now(),
+    });
+    const identity = binding(await this.client.session()),
+      store = this.store(input.operationId);
+    await store.locked(
+      () => store.write({ formatVersion: 1, binding: identity, input, state: 'prepared' }),
+      this.client.transport.signal,
+    );
+    return { operationId: input.operationId, state: 'prepared', request: input };
+  }
+  async inspect(id) {
+    const row = await this.store(id).read();
+    if (!row || row.formatVersion !== 1 || row.input?.operationId !== id) {
+      fail('operation_not_found', 'This context has no valid local operation with that ID.');
+    }
+    return {
+      operationId: id,
+      source: 'local_journal',
+      state: row.state,
+      request: row.input,
+      ...(row.receipt ? { receipt: row.receipt } : {}),
+      ...(row.error ? { error: row.error } : {}),
+    };
+  }
+  async execute(value) {
+    const input = validateCommand(value),
+      store = this.store(input.operationId);
+    return store.locked(async () => {
+      // Capture token and identity together under the refresh lock. A later
+      // logout/login cannot turn this pending operation into another profile.
+      const session = await this.client.authorizedSession(),
+        identity = binding(session);
+      let row = await store.read();
+      if (row && (row.formatVersion !== 1 || canonical(row.binding) !== canonical(identity))) {
+        fail(
+          'operation_identity_mismatch',
+          'This operation belongs to another connection, profile, session or environment.',
+          {
+            remediation:
+              'Inspect it locally and reread current records. Do not replay it through a replacement login.',
+          },
+        );
+      }
+      if (row && canonical(row.input) !== canonical(input)) {
+        fail(
+          'idempotency_mismatch',
+          'The operation ID already belongs to a different immutable request.',
+          { status: 409, remediation: 'Use commands inspect, then retry the saved operation.' },
+        );
+      }
+      if (row?.state === 'confirmed') {
+        return { source: 'local_receipt', receipt: row.receipt };
+      }
+      row = { formatVersion: 1, binding: identity, input, state: 'uncertain' };
+      await store.write(row);
+      try {
+        const receipt = await this.client.transport.request('/api/agents/v1/commands', {
+          method: 'POST',
+          json: input,
+          token: session.access_token,
+        });
+        if (
+          !receiptSchema.safeParse(receipt).success ||
+          ['operationId', 'scope', 'kind', 'epoch'].some((key) => receipt[key] !== input[key])
+        ) {
+          fail(
+            'invalid_response',
+            'The command receipt was invalid. The server may have committed.',
+            { execution: 'unknown', remediation: 'Retry the identical saved operation.' },
+          );
+        }
+        await store.write({ ...row, state: 'confirmed', receipt });
+        return { source: 'server', receipt };
+      } catch (error) {
+        const safe = safeError(error);
+        const result = new AgentError(safe.code, safe.message, {
+          status: safe.status,
+          retryable: safe.retryable,
+          remediation: safe.remediation,
+          execution: 'unknown',
+          ...safe.details,
+          operationId: input.operationId,
+        });
+        // The uncertainty marker is already durable. Preserve the useful original
+        // error/operation ID even if disk pressure prevents saving diagnostics.
+        await store.write({ ...row, error: result.toJSON() }).catch(() => {});
+        throw result;
+      }
+    }, this.client.transport.signal);
+  }
+  async retry(id) {
+    return this.execute((await this.inspect(id)).request);
+  }
+}

package/src/errors.mjs

@@ -0,0 +1,65 @@
+/** Never forward raw network exceptions: URLs, HTML and provider diagnostics
+ * can contain credentials. API messages are data, never terminal control. */
+export class AgentError extends Error {
+  constructor(
+    code,
+    message,
+    { status = 0, retryable = false, remediation = 'Check help and retry.', ...details } = {},
+  ) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.retryable = retryable;
+    this.remediation = remediation;
+    this.details = details;
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      remediation: this.remediation,
+      ...this.details,
+    };
+  }
+}
+export const fail = (code, message, options) => {
+  throw new AgentError(code, message, options);
+};
+export function safeError(error) {
+  return error instanceof AgentError
+    ? error
+    : new AgentError('internal_error', 'The command could not complete.', {
+        remediation: 'Retry once; run doctor if the problem persists.',
+      });
+}
+export function exitCode(error) {
+  if (['invalid_arguments', 'invalid_origin'].includes(error.code)) {
+    return 2;
+  }
+  if (
+    error.status === 401 ||
+    [
+      'not_authenticated',
+      'reauthentication_required',
+      'access_denied',
+      'expired_token',
+      'invalid_grant',
+    ].includes(error.code)
+  ) {
+    return 3;
+  }
+  if (error.status === 403 || error.code === 'profile_selection_denied') {
+    return 4;
+  }
+  if (error.status === 409 || error.code === 'profile_selection_conflict') {
+    return 5;
+  }
+  if (error.status === 429) {
+    return 6;
+  }
+  if (error.retryable) {
+    return 7;
+  }
+  return 1;
+}

package/src/fitness.mjs

@@ -0,0 +1,267 @@
+import * as z from 'zod/v4';
+import catalog from './command-catalog.mjs';
+import { fail } from './errors.mjs';
+
+const id = z
+  .string()
+  .min(1)
+  .max(256)
+  // eslint-disable-next-line no-control-regex -- Match the server identifier boundary.
+  .regex(/^[^\u0000-\u001f]+$/u);
+const scope = z
+  .string()
+  .max(256)
+  // eslint-disable-next-line no-control-regex -- Scope prefixes bind records to the right owner.
+  .regex(/^(project|personal):[^\u0000-\u001f]+$/u);
+const revision = z
+  .string()
+  .regex(/^(0|[1-9][0-9]{0,15})$/)
+  .refine((value) => BigInt(value) <= 9007199254740991n);
+const date = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/)
+  .refine(
+    (value) =>
+      Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value,
+  );
+
+export const catalogSchema = z
+  .object({
+    query: z.string().max(160).optional(),
+    key: z
+      .string()
+      .regex(/^ex\.[0-9]+$/)
+      .optional(),
+    equipment: z.string().max(80).optional(),
+    muscle: z.string().max(80).optional(),
+    after: z
+      .string()
+      .regex(/^ex\.[0-9]+$/)
+      .optional(),
+    version: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .optional(),
+  })
+  .strict()
+  .refine((input) => !input.after || (!!input.version && !input.key));
+export const metricsSchema = z
+  .object({
+    scope: z.string().regex(/^project:[A-Za-z0-9_-]{1,128}$/),
+    from: date,
+    until: date,
+  })
+  .strict()
+  .refine((input) => {
+    const days = (Date.parse(input.until) - Date.parse(input.from)) / 86400000;
+    return days >= 0 && days < 366;
+  });
+export const resourcesSchema = z
+  .object({
+    scope,
+    collection: z.enum(Object.keys(catalog.collections)),
+    id: id.optional(),
+    after: id.optional(),
+    epoch: id.optional(),
+    checkpoint: revision.optional(),
+    archive: z.enum(['active', 'archived', 'all']).optional(),
+  })
+  .strict()
+  .refine(
+    (input) =>
+      (!input.after || (!!input.epoch && input.checkpoint !== undefined && !input.id)) &&
+      (input.archive === undefined || input.collection === 'planning' || input.archive === 'all') &&
+      input.scope.startsWith(
+        catalog.collections[input.collection].module.startsWith('LocalUser/')
+          ? 'personal:'
+          : 'project:',
+      ),
+  );
+
+const checked = (schema, input) => {
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    fail(
+      'invalid_arguments',
+      'Use the declared parameters, matching scope and bounded dates. Continue pages with the returned version or epoch/checkpoint.',
+    );
+  }
+  return result.data;
+};
+const exerciseSchema = z
+  .object({
+    key: z.string().regex(/^ex\.[0-9]+$/),
+    name: z.string().min(1),
+    bodyPart: z.string(),
+    target: z.string(),
+    secondary: z.array(z.string()).max(30),
+    equipment: z.string(),
+    equipmentGroup: z.string(),
+    muscleGroup: z.string(),
+    exerciseType: z.string(),
+    attribution: z.string(),
+  })
+  .strict();
+const catalogPage = z
+  .object({
+    version: z.string().regex(/^[a-f0-9]{64}$/),
+    items: z.array(exerciseSchema).max(25),
+    nextAfter: z.string().nullable(),
+  })
+  .strict();
+
+/** Catalogue IDs, not copied image files, connect imported exercises to the
+ * app's maintained library. Every request still uses the current delegation. */
+export async function readCatalog(client, input) {
+  const query = checked(catalogSchema, input),
+    result = await client.get('catalog', query);
+  if (
+    !catalogPage.safeParse(result).success ||
+    (query.version && result.version !== query.version) ||
+    (query.key && (result.items.length !== 1 || result.items[0].key !== query.key)) ||
+    new Set(result.items.map((item) => item.key)).size !== result.items.length ||
+    (result.nextAfter !== null &&
+      (!result.items.length || result.nextAfter !== result.items.at(-1).key)) ||
+    result.items.some(
+      (item, index) =>
+        (query.after && item.key <= query.after) ||
+        (index > 0 && item.key <= result.items[index - 1].key),
+    )
+  ) {
+    fail(
+      'invalid_response',
+      'The catalogue page was invalid. Keep the previous cursor and do not import unknown IDs.',
+    );
+  }
+  return result;
+}
+
+const metricsPage = z
+  .object({
+    scope,
+    epoch: id,
+    checkpoint: revision,
+    from: date,
+    until: date,
+    days: z
+      .array(
+        z
+          .object({
+            day: date,
+            sessions: z.number().int().nonnegative().safe(),
+            runs: z.number().int().nonnegative().safe(),
+            durationSeconds: z.number().nonnegative(),
+            distanceMeters: z.number().nonnegative(),
+          })
+          .strict(),
+      )
+      .max(366),
+  })
+  .strict();
+
+/** Daily aggregates keep long activity histories out of agent context. A failed
+ * or partial response is never summarized as zero activity. */
+export async function readMetrics(client, input) {
+  const query = checked(metricsSchema, input),
+    result = await client.get('metrics', query);
+  if (
+    !metricsPage.safeParse(result).success ||
+    ['scope', 'from', 'until'].some((key) => result[key] !== query[key]) ||
+    result.days.some(
+      (day, index) =>
+        day.day < query.from ||
+        day.day > query.until ||
+        (index > 0 && day.day <= result.days[index - 1].day),
+    )
+  ) {
+    fail(
+      'invalid_response',
+      'The metrics response was invalid. Do not infer empty activity from it.',
+    );
+  }
+  return result;
+}
+
+const resourcePage = z
+  .object({
+    scope,
+    collection: z.string(),
+    epoch: id,
+    checkpoint: revision,
+    items: z
+      .array(z.object({ id, revision, data: z.record(z.string(), z.unknown()) }).strict())
+      .max(25),
+    omittedIds: z.array(id).max(25),
+    nextAfter: id.nullable(),
+    changeCursor: z.string().max(4096).nullable(),
+    etag: z.string().max(8192),
+    notModified: z.boolean().optional(),
+  })
+  .strict();
+export async function readResources(client, input) {
+  const query = checked(resourcesSchema, input),
+    result = await client.get('resources', query);
+  if (
+    !resourcePage.safeParse(result).success ||
+    result.scope !== query.scope ||
+    result.collection !== query.collection ||
+    (query.epoch && result.epoch !== query.epoch) ||
+    (query.checkpoint && result.checkpoint !== query.checkpoint) ||
+    (query.id && result.items.some((item) => item.id !== query.id)) ||
+    new Set(result.items.map((item) => item.id)).size !== result.items.length ||
+    (query.after &&
+      ((result.nextAfter !== null && result.nextAfter <= query.after) ||
+        result.items.some((item) => item.id <= query.after)))
+  ) {
+    fail(
+      'invalid_response',
+      'The resource page was invalid. Preserve the previous inventory and cursor.',
+    );
+  }
+  return result;
+}
+
+/** Local, reviewed contract subset. Only this command's editable fields are
+ * returned; private server models never enter the distributed client. */
+export function commandHelp(kind) {
+  if (typeof kind !== 'string' || !Object.hasOwn(catalog.commands, kind)) {
+    fail('invalid_arguments', 'Choose a command from capabilities or commands describe.');
+  }
+  const definition = catalog.commands[kind],
+    properties = {};
+  for (const field of definition.fields) {
+    properties[field] = catalog.fieldSchemas[definition.module][field];
+  }
+  const required = definition.create
+    ? definition.fields.filter((field) => {
+        const schema = properties[field];
+        return (
+          !Object.hasOwn(schema, 'default') &&
+          !(
+            schema.type === 'null' ||
+            (Array.isArray(schema.type) && schema.type.includes('null')) ||
+            schema.anyOf?.some((part) => part.type === 'null')
+          )
+        );
+      })
+    : [];
+  for (const field of definition.requiredFields ?? []) {
+    if (!required.includes(field)) {
+      required.push(field);
+    }
+    const schema = properties[field];
+    if (schema.anyOf?.some((part) => part.type === 'null')) {
+      properties[field] = { ...schema, anyOf: schema.anyOf.filter((part) => part.type !== 'null') };
+    }
+  }
+  return {
+    kind,
+    ...definition,
+    dataSchema: { type: 'object', properties, required, additionalProperties: false },
+    workflow: definition.create
+      ? 'Use a new stable ID and null expectedRevision; read the scope epoch first. program.create uses its UUID as initial epoch and needs all-resources consent.'
+      : 'Read the current record and use its revision. Preserve the prepared operation after an uncertain response.',
+    coach:
+      'Other athletes’ programs need current Coach subscription, coaching:write and ordinary program access.',
+  };
+}