outask 0.0.0-stage → 1.7.0

package/src/create.mjs

@@ -0,0 +1,145 @@
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail } from './errors.mjs';
+import { mutationProject, selectStore, withDestination } from './destinations.mjs';
+import { nextTimestamp } from './timestamps.mjs';
+import { projectBudget, readArray } from './input.mjs';
+import { inputBytes, projectBytes, responseBytes } from './limits.mjs';
+import { jsonBytes } from './response.mjs';
+import { knownCounter, readService, recoverMove, replaceFile, serviceState, withProjectLock } from './service.mjs';
+import { finishStore, formatValue } from './storage-format.mjs';
+import { effectiveRecord, openProject, projectRelative, retainedFiles, serviceFile } from './stores.mjs';
+import { scanProject, validateCycles, validateRecord } from './validation.mjs';
+
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const sameFiles = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+
+function taskInput(input) {
+  if (!object(input)) fail('INVALID_INPUT', 'task input must be a JSON object');
+  let source;
+  try {
+    source = JSON.stringify(input, (key, value) => {
+      if (['undefined', 'function', 'symbol', 'bigint'].includes(typeof value)
+        || (typeof value === 'number' && !Number.isFinite(value))) {
+        fail('INVALID_INPUT', 'task input must contain only JSON values');
+      }
+      return value;
+    });
+  } catch (error) {
+    if (error.code === 'INVALID_INPUT') throw error;
+    fail('INVALID_INPUT', 'task input must contain only JSON values without circular references');
+  }
+  if (Buffer.byteLength(source, 'utf8') > inputBytes) fail('INPUT_TOO_LARGE', 'task input exceeds the 8 MiB read budget');
+  const task = JSON.parse(source);
+  if (!object(task)) fail('INVALID_INPUT', 'task input must be a JSON object');
+  if (task.id !== undefined && (!Number.isSafeInteger(task.id) || task.id <= 0)) {
+    fail('INVALID_INPUT', 'id must be a positive safe integer');
+  }
+  return task;
+}
+
+function readActive(project, target, fingerprints) {
+  const budget = { ...projectBudget(), fingerprints: {} };
+  const active = new Map();
+  const activeIds = new Set();
+  let source;
+  let count;
+  const retained = new Set(retainedFiles(project));
+  for (const [file, rules] of Object.entries(project.stores)) {
+    if (!retained.has(file)) continue;
+    const activeStore = rules.statuses.some((status) => project.groups.get(status) === 'Active');
+    if (file !== target && !activeStore) continue;
+    const path = join(project.directory, file);
+    const { source: text, records } = readArray(path, budget);
+    if (budget.fingerprints[path] !== fingerprints[projectRelative(project.root, path)]) {
+      fail('PROJECT_CHANGED', 'task files changed before creation; retry after edits finish');
+    }
+    if (file === target) {
+      source = text;
+      count = 0;
+    }
+    for (const { value } of records) {
+      if (file === target) count++;
+      if (!activeStore) continue;
+      const record = rules.validate === false && rules.missing_status === undefined ? value : effectiveRecord(value, project, file, `tasks/${file}`);
+      if (project.groups.get(record.status) !== 'Active') continue;
+      activeIds.add(record.id);
+      if (rules.validate !== false) active.set(record.id, { blockers: record.blockers ?? [] });
+    }
+  }
+  return { active, activeIds, source, count };
+}
+
+export function createTask(projectPath, input, options = {}) {
+  const supplied = taskInput(input);
+  if (Object.hasOwn(supplied, 'updated_at')) fail('INVALID_INPUT', 'updated_at is tracker-owned; omit it when creating a task');
+  if (!object(options) || Object.keys(options).some((key) => !['store', 'schemaPath'].includes(key))
+    || (options.store !== undefined && (typeof options.store !== 'string' || !options.store.trim()))) {
+    fail('INVALID_INPUT', 'options must contain only optional store and schemaPath values');
+  }
+  const initial = openProject(projectPath, undefined, true, true, options.schemaPath);
+  return withProjectLock(initial, 'creation', () => {
+    recoverMove(initial);
+    const destinations = mutationProject(openProject(initial.root, undefined, false, true, initial.schema));
+    const status = supplied.status === undefined ? (destinations.config?.default_status ?? 'pending') : supplied.status;
+    return withDestination(destinations, status, options.store, () => {
+      const service = readService(initial);
+      let snapshot = scanProject(initial.root, false, initial.schema);
+      let counter = service.counter;
+      if (counter === undefined || service.validated?.counter !== counter || !sameFiles(service.validated?.files, snapshot.fingerprints)
+        || (supplied.id !== undefined && supplied.id <= counter)) {
+        snapshot = scanProject(initial.root, true, initial.schema);
+        counter = Math.max(knownCounter(service), snapshot.maximum);
+        if (snapshot.ids.has(supplied.id)) fail('ID_CONFLICT', `task id ${supplied.id} already exists at ${snapshot.ids.get(supplied.id)}`);
+      }
+      const id = supplied.id ?? counter + 1;
+      if (!Number.isSafeInteger(id)) fail('ID_EXHAUSTED', 'the task ID counter has reached the largest safe integer; automatic allocation is unavailable');
+      const { project } = snapshot;
+      const target = selectStore(project, status, options.store);
+      const defaults = project.config?.format === 'minimal' ? {} : { priority: 'medium', blockers: [] };
+      const task = { id, title: supplied.title, status, ...defaults, ...supplied, updated_at: nextTimestamp() };
+      validateRecord(task, 'new task', project, target);
+      if (task.blockers?.includes(id)) fail('INVALID_STORE', `task ${id}: blockers must not contain its own id`);
+      const selected = readActive(project, target, snapshot.fingerprints);
+      const working = project.config?.working_statuses ?? ['in_progress', 'review'];
+      if (working.includes(status)) {
+        const blockers = [...new Set((task.blockers ?? []).filter((blocker) => selected.activeIds.has(blocker)))].sort((a, b) => a - b);
+        if (blockers.length) fail('ACTIVE_BLOCKERS', `task ${id} cannot enter ${status}; Active blockers: ${blockers.join(', ')}`);
+      }
+      if (project.groups.get(status) === 'Active') selected.active.set(id, task);
+      validateCycles(selected.active);
+      if (jsonBytes(task) + 1 > responseBytes) {
+        fail('OUTPUT_TOO_LARGE', 'the complete created task exceeds 32 KiB; shorten the task input before creating it');
+      }
+      // Append to the original array so unrelated numeric literals and formatting survive.
+      const end = selected.source.lastIndexOf(0x5d);
+      let contentEnd = end;
+      while ([0x20, 0x09, 0x0a, 0x0d].includes(selected.source[contentEnd - 1])) contentEnd--;
+      const record = Buffer.from(`  ${formatValue(task, '  ')}`);
+      const source = finishStore(Buffer.concat([
+        selected.source.subarray(0, contentEnd), Buffer.from(`${selected.count ? ',' : ''}\n`),
+        record, Buffer.from('\n'), selected.source.subarray(end),
+      ]));
+      if (source.length - selected.source.length > project.budget.remaining) {
+        fail('INPUT_TOO_LARGE', `creating this task would exceed the ${projectBytes / 1024 / 1024} MiB project source budget; reduce retained input first`);
+      }
+      const path = join(project.directory, target);
+      const fingerprints = { ...snapshot.fingerprints, [projectRelative(project.root, path)]: createHash('sha256').update(source).digest('hex') };
+      const state = serviceState(service, Math.max(counter, id), fingerprints);
+      if (jsonBytes(state, 2, inputBytes) + 1 > inputBytes) fail('INPUT_TOO_LARGE', 'resulting service state would exceed its 8 MiB read budget');
+      const stateSource = `${JSON.stringify(state, null, 2)}\n`;
+      const current = scanProject(project.root, false, project.schema);
+      if (!sameFiles(snapshot.fingerprints, current.fingerprints)) {
+        fail('PROJECT_CHANGED', 'task files or configuration changed during creation; retry after edits finish');
+      }
+      replaceFile(path, source, statSync(path).mode & 0o777);
+      try {
+        replaceFile(join(project.directory, serviceFile), stateSource);
+      } catch (error) {
+        fail('WRITE_INCOMPLETE', `task ${id} was saved to tasks/${target}, but service refresh failed (${error.code}); inspect that task and validate the project before creating again; do not blindly repeat the request`);
+      }
+      return task;
+    });
+  }, 5000);
+}

package/src/cursor.mjs

@@ -0,0 +1,30 @@
+import { createHash } from 'node:crypto';
+import { fail } from './errors.mjs';
+
+const isText = (value) => typeof value === 'string' && value.trim() !== '';
+
+export function cursorBinding(value) {
+  return createHash('sha256').update(JSON.stringify(value)).digest('base64url');
+}
+
+export function encodeCursor(offset, binding) {
+  return Buffer.from(JSON.stringify({ v: 1, o: offset, b: binding })).toString('base64url');
+}
+
+export function decodeCursor(cursor, binding, operation) {
+  if (cursor === undefined) return 0;
+  if (!isText(cursor) || !/^[A-Za-z0-9_-]+$/.test(cursor)) {
+    fail('INVALID_CURSOR', `cursor is invalid; start a new ${operation}`);
+  }
+  try {
+    const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+      || value.v !== 1 || !Number.isSafeInteger(value.o) || value.o < 0 || value.b !== binding) {
+      fail('INVALID_CURSOR', `cursor does not belong to this ${operation}; start a new ${operation}`);
+    }
+    return value.o;
+  } catch (error) {
+    if (error.code === 'INVALID_CURSOR') throw error;
+    fail('INVALID_CURSOR', `cursor is invalid; start a new ${operation}`);
+  }
+}

package/src/destinations.mjs

@@ -0,0 +1,74 @@
+import { closeSync, existsSync, fstatSync, lstatSync, openSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pendingFile, standardStores } from './stores.mjs';
+import { readText } from './input.mjs';
+import { fail } from './errors.mjs';
+
+export function configuredStatuses(project, group) {
+  return [...new Set(Object.values(project.stores).flatMap((rules) => rules.statuses))]
+    .filter((status) => group === undefined || project.groups.get(status) === group).sort();
+}
+
+export function validateStatuses(project, supplied) {
+  const allowed = configuredStatuses(project);
+  const unknown = Object.entries(supplied).filter(([, status]) => !allowed.includes(status));
+  if (unknown.length) {
+    const values = unknown.map(([name, status]) => `${name}=${JSON.stringify(status)}`).join(', ');
+    fail('INVALID_INPUT', `unknown status values: ${values}; allowed configured statuses: ${allowed.join(', ')}`);
+  }
+}
+
+export function selectStore(project, status, requested) {
+  validateStatuses(project, { status });
+  const candidates = Object.keys(project.stores).filter((file) => project.stores[file].statuses.includes(status)).sort();
+  if (requested !== undefined) {
+    const name = requested.endsWith('.json') ? requested : `${requested}.json`;
+    if (!candidates.includes(name)) {
+      fail('INVALID_INPUT', `store ${JSON.stringify(requested)} is not a configured destination for status ${JSON.stringify(status)}; allowed destination stores: ${candidates.join(', ')}`);
+    }
+    return name;
+  }
+  if (candidates.length > 1) {
+    fail('INVALID_INPUT', `status ${JSON.stringify(status)} has multiple destinations; select --store from: ${candidates.join(', ')}`);
+  }
+  return candidates[0];
+}
+
+// The caller owns the project lock; custom filenames always require explicit files.
+export function withDestination(project, status, requested, operation) {
+  const target = selectStore(project, status, requested);
+  const path = join(project.directory, target);
+  let created;
+  if (Object.hasOwn(standardStores, target)) {
+    try { lstatSync(path); } catch (error) {
+      if (error.code !== 'ENOENT') fail('READ_ERROR', `${path}: cannot inspect destination (${error.code})`);
+      try {
+        const descriptor = openSync(path, 'wx', 0o644);
+        try {
+          writeFileSync(descriptor, '[]\n');
+          created = fstatSync(descriptor, { bigint: true });
+        } finally { closeSync(descriptor); }
+      } catch (writeError) {
+        fail('WRITE_ERROR', `${path}: cannot create destination (${writeError.code})`);
+      }
+    }
+  }
+  try { return operation(); } catch (error) {
+    if (created && error.code !== 'WRITE_INCOMPLETE' && !existsSync(join(project.directory, pendingFile))) {
+      let unchanged = false;
+      try {
+        const current = lstatSync(path, { bigint: true });
+        unchanged = ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs', 'mode'].every((key) => current[key] === created[key])
+          && readText(path, { remaining: 3 }) === '[]\n';
+      } catch {
+        // An inaccessible, removed or changed file belongs to the external writer.
+      }
+      if (unchanged) unlinkSync(path);
+    }
+    throw error;
+  }
+}
+
+export function mutationProject(project) {
+  return project.config ? project : { ...project, stores: standardStores };
+}

package/src/errors.mjs

@@ -0,0 +1,16 @@
+export function fail(code, message) {
+  const error = new Error(errorText(message));
+  error.code = code;
+  throw error;
+}
+
+export function errorText(message) {
+  let bytes = 0;
+  let end = 0;
+  for (const character of message) {
+    bytes += Buffer.byteLength(character, 'utf8');
+    if (bytes > 2048) return `${message.slice(0, end)}…`;
+    end += character.length;
+  }
+  return message;
+}

package/src/field-rules.mjs

@@ -0,0 +1,105 @@
+import { fail } from './errors.mjs';
+import { timestampValue } from './timestamps.mjs';
+
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = (value) => typeof value === 'string' && value.trim() !== '';
+const ruleTypes = new Set(['string', 'array', 'number', 'integer', 'boolean', 'object', 'date', 'timestamp']);
+const itemTypes = new Set(['string', 'number', 'integer', 'boolean', 'object', 'date', 'timestamp']);
+
+function invalidConfig(path, message) {
+  fail('INVALID_CONFIG', `${path}: ${message}`);
+}
+
+function validateRule(rule, path, statuses) {
+  if (!object(rule)) invalidConfig(path, 'field rule must be an object');
+  const allowed = ['type', 'required', 'required_for_statuses', 'non_empty', 'items', 'non_empty_items', 'min_items'];
+  for (const key of Object.keys(rule)) if (!allowed.includes(key)) invalidConfig(path, `unsupported field rule key ${key}`);
+  if (rule.type !== undefined && !ruleTypes.has(rule.type)) {
+    invalidConfig(path, `type must be one of ${[...ruleTypes].join(', ')}`);
+  }
+  if (rule.required !== undefined && typeof rule.required !== 'boolean') invalidConfig(path, 'required must be a boolean');
+  if (rule.non_empty !== undefined && typeof rule.non_empty !== 'boolean') invalidConfig(path, 'non_empty must be a boolean');
+  if (rule.non_empty_items !== undefined && typeof rule.non_empty_items !== 'boolean') {
+    invalidConfig(path, 'non_empty_items must be a boolean');
+  }
+  if (rule.items !== undefined && !itemTypes.has(rule.items)) {
+    invalidConfig(path, `items must be one of ${[...itemTypes].join(', ')}`);
+  }
+  if (rule.min_items !== undefined && (!Number.isSafeInteger(rule.min_items) || rule.min_items < 0)) {
+    invalidConfig(path, 'min_items must be a non-negative safe integer');
+  }
+  if (rule.required_for_statuses !== undefined) {
+    if (!Array.isArray(rule.required_for_statuses) || !rule.required_for_statuses.every(text)) {
+      invalidConfig(path, 'required_for_statuses must be an array of non-empty strings');
+    }
+    for (const status of rule.required_for_statuses) {
+      if (!statuses.has(status)) invalidConfig(path, `required_for_statuses references undeclared status ${status}`);
+    }
+  }
+  if ((rule.items !== undefined || rule.non_empty_items !== undefined || rule.min_items !== undefined)
+    && rule.type !== undefined && rule.type !== 'array') {
+    invalidConfig(path, 'items, non_empty_items and min_items require type array');
+  }
+}
+
+export function validateFieldRules(rules, path, statuses) {
+  if (rules === undefined) return;
+  if (!object(rules)) invalidConfig(path, 'fields must be an object');
+  for (const [field, rule] of Object.entries(rules)) {
+    if (!text(field)) invalidConfig(path, 'field names must be non-empty strings');
+    validateRule(rule, `${path}.fields.${field}`, statuses);
+  }
+}
+
+function present(task, field, label, invalid) {
+  if (!Object.hasOwn(task, field) || task[field] === null || task[field] === undefined) {
+    invalid(field, `is required by ${label}`);
+    return false;
+  }
+  return true;
+}
+
+function validDate(value) {
+  return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+
+function checkType(value, type, label, invalid) {
+  if (type === undefined) return;
+  if (type === 'string' && typeof value !== 'string') invalid(label, 'must be a string');
+  else if (type === 'array' && !Array.isArray(value)) invalid(label, 'must be an array');
+  else if (type === 'number' && (typeof value !== 'number' || !Number.isFinite(value))) invalid(label, 'must be a finite number');
+  else if (type === 'integer' && !Number.isSafeInteger(value)) invalid(label, 'must be a safe integer');
+  else if (type === 'boolean' && typeof value !== 'boolean') invalid(label, 'must be a boolean');
+  else if (type === 'object' && !object(value)) invalid(label, 'must be an object');
+  else if (type === 'date' && !validDate(value)) invalid(label, 'must be a valid date string');
+  else if (type === 'timestamp') timestampValue(value, 'INVALID_STORE', label);
+}
+
+function validateItems(values, type, field, invalid, nonEmpty) {
+  if (type === undefined) return;
+  values.forEach((value, index) => {
+    const label = `${field}[${index}]`;
+    checkType(value, type, label, invalid);
+    if (nonEmpty && typeof value === 'string' && !text(value)) invalid(label, 'must be a non-empty string');
+  });
+}
+
+export function applyFieldRules(task, rules, status, label, invalid) {
+  for (const [field, rule] of Object.entries(rules ?? {})) {
+    const required = rule.required === true || (rule.required_for_statuses ?? []).includes(status);
+    if (required && !present(task, field, label, invalid)) continue;
+    if (!Object.hasOwn(task, field) || task[field] === undefined || task[field] === null) continue;
+    const value = task[field];
+    checkType(value, rule.type, field, invalid);
+    if (rule.non_empty === true) {
+      if (typeof value === 'string' && !text(value)) invalid(field, 'must be a non-empty string');
+      if (Array.isArray(value) && value.length === 0) invalid(field, 'must be a non-empty array');
+    }
+    if (Array.isArray(value)) {
+      if (rule.min_items !== undefined && value.length < rule.min_items) {
+        invalid(field, `must contain at least ${rule.min_items} item${rule.min_items === 1 ? '' : 's'}`);
+      }
+      validateItems(value, rule.items, field, invalid, rule.non_empty_items === true);
+    }
+  }
+}

package/src/fields.mjs

@@ -0,0 +1,32 @@
+import { fail } from './errors.mjs';
+
+export const defaultFields = ['id', 'title', 'status'];
+export const ownValue = (task, field) => Object.hasOwn(task, field) ? task[field] : undefined;
+
+export function fieldsFor(fields, records) {
+  if (!Array.isArray(fields) || fields.length === 0
+    || !fields.every((field) => typeof field === 'string' && field.trim() !== '')) {
+    fail('INVALID_INPUT', 'fields must be a non-empty array of field names or ["all"]');
+  }
+  if (fields.includes('all')) {
+    if (fields.length !== 1) fail('INVALID_INPUT', 'all must be the only requested field');
+    const names = new Set();
+    for (const record of records) for (const name of Object.keys(record)) names.add(name);
+    return [...names];
+  }
+  return [...new Set(fields)];
+}
+
+export function checkFields(fields, records) {
+  const available = new Set([...defaultFields, 'priority', 'blockers', 'updated_at']);
+  for (const record of records) for (const name of Object.keys(record)) available.add(name);
+  for (const field of fields) {
+    if (records.length && !available.has(field)) {
+      fail('INVALID_INPUT', `unknown field ${field}; use --fields all to inspect available task fields`);
+    }
+  }
+}
+
+export function projectFields(task, fields) {
+  return Object.fromEntries(fields.filter((field) => Object.hasOwn(task, field)).map((field) => [field, task[field]]));
+}

package/src/input.mjs

@@ -0,0 +1,146 @@
+import { isUtf8 } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+import { fail } from './errors.mjs';
+import { inputBytes, projectBytes } from './limits.mjs';
+
+export function readBudget() {
+  return { remaining: inputBytes, limit: inputBytes };
+}
+
+export function projectBudget() {
+  return { remaining: projectBytes, limit: projectBytes };
+}
+
+export function decodeText(source, label) {
+  if (!isUtf8(source)) fail('INVALID_JSON', `${label}: invalid UTF-8; correct the input and retry`);
+  return source.toString('utf8');
+}
+
+function tooLarge(path, budget) {
+  const limit = budget.limit ?? inputBytes;
+  fail('INPUT_TOO_LARGE', `${path}: selected JSON input exceeds the ${limit / 1024 / 1024} MiB read budget; select fewer stores or reduce the file size`);
+}
+
+export function readBuffer(path, budget, optional = false) {
+  let descriptor;
+  try {
+    descriptor = openSync(path, 'r');
+  } catch (error) {
+    if (optional && error.code === 'ENOENT') {
+      if (budget.fingerprints) budget.fingerprints[path] = null;
+      return undefined;
+    }
+    fail('READ_ERROR', `${path}: cannot read file (${error.code}); check the path and permissions`);
+  }
+  try {
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile()) fail('READ_ERROR', `${path}: expected a regular file; check the path`);
+    if (stat.size > budget.remaining) tooLarge(path, budget);
+    const chunks = [];
+    let length = 0;
+    // Reads stay bounded even if a file grows after the initial size check.
+    while (budget.remaining > 0) {
+      const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, budget.remaining));
+      const count = readSync(descriptor, chunk, 0, chunk.length, null);
+      if (count === 0) break;
+      budget.remaining -= count;
+      length += count;
+      chunks.push(chunk.subarray(0, count));
+    }
+    if (fstatSync(descriptor).size > length) tooLarge(path, budget);
+    const source = Buffer.concat(chunks, length);
+    if (budget.fingerprints) budget.fingerprints[path] = createHash('sha256').update(source).digest('hex');
+    return source;
+  } catch (error) {
+    if (['INPUT_TOO_LARGE', 'READ_ERROR', 'INVALID_JSON'].includes(error.code)) throw error;
+    fail('READ_ERROR', `${path}: cannot read file (${error.code}); check the path and permissions`);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+export function readText(path, budget, optional = false) {
+  const source = readBuffer(path, budget, optional);
+  return source === undefined ? undefined : decodeText(source, path);
+}
+
+export function readJson(path, budget, optional = false) {
+  const source = readText(path, budget, optional);
+  if (source === undefined) return undefined;
+  return parseJson(source, path);
+}
+
+export function parseJson(source, label) {
+  try {
+    return JSON.parse(source);
+  } catch {
+    fail('INVALID_JSON', `${label}: invalid JSON; correct the input and retry`);
+  }
+}
+
+const whitespace = (byte) => byte === 0x20 || byte === 0x09 || byte === 0x0a || byte === 0x0d;
+
+export function* arrayRecords(source, label) {
+  if (!isUtf8(source)) fail('INVALID_JSON', `${label}: invalid UTF-8; correct the input and retry`);
+  let offset = 0;
+  while (whitespace(source[offset])) offset++;
+  if (source[offset++] !== 0x5b) fail('INVALID_JSON', `${label}: invalid JSON; correct the input and retry`);
+  let index = 0;
+  while (true) {
+    while (whitespace(source[offset])) offset++;
+    if (source[offset] === 0x5d) {
+      offset++;
+      while (whitespace(source[offset])) offset++;
+      if (offset !== source.length) fail('INVALID_JSON', `${label}: invalid JSON; correct the input and retry`);
+      return;
+    }
+    const start = offset;
+    let depth = 0;
+    let string = false;
+    let escaped = false;
+    for (; offset < source.length; offset++) {
+      const byte = source[offset];
+      if (string) {
+        if (escaped) escaped = false;
+        else if (byte === 0x5c) escaped = true;
+        else if (byte === 0x22) string = false;
+        continue;
+      }
+      if (byte === 0x22) string = true;
+      else if (byte === 0x7b || byte === 0x5b) depth++;
+      else if (byte === 0x7d || byte === 0x5d) {
+        if (byte === 0x5d && depth === 0) break;
+        depth--;
+      } else if (byte === 0x2c && depth === 0) break;
+    }
+    const end = offset;
+    let value;
+    try { value = JSON.parse(source.toString('utf8', start, end)); } catch {
+      fail('INVALID_JSON', `${label}: invalid JSON; correct the input and retry`);
+    }
+    yield { value, index, start, end };
+    index++;
+    if (source[offset] === 0x2c) {
+      offset++;
+      while (whitespace(source[offset])) offset++;
+      if (source[offset] === 0x5d) fail('INVALID_JSON', `${label}: invalid JSON; correct the input and retry`);
+      continue;
+    }
+    if (source[offset] !== 0x5d) fail('INVALID_JSON', `${label}: invalid JSON; correct the input and retry`);
+  }
+}
+
+export function readArray(path, budget) {
+  const source = readBuffer(path, budget);
+  let offset = 0;
+  while (whitespace(source[offset])) offset++;
+  if (source[offset] !== 0x5b) {
+    let value;
+    try { value = JSON.parse(decodeText(source, path)); } catch {
+      fail('INVALID_JSON', `${path}: invalid JSON; correct the input and retry`);
+    }
+    if (!Array.isArray(value)) fail('INVALID_STORE', `${path}: root value must be an array`);
+  }
+  return { source, records: arrayRecords(source, path) };
+}

package/src/limits.mjs

@@ -0,0 +1,5 @@
+export const defaultLimit = 10;
+export const maxLimit = 50;
+export const responseBytes = 32 * 1024;
+export const inputBytes = 8 * 1024 * 1024;
+export const projectBytes = 128 * 1024 * 1024;

package/src/locations.mjs

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// Explicit XDG locations remain supported; packaged application files always
+// use the platform application root, independently of cache/config overrides.
+export function applicationRoot(env = process.env, platform = process.platform) {
+  const home = platform === 'win32' ? env.USERPROFILE || homedir() : env.HOME || homedir();
+  if (platform === 'win32') return join(env.LOCALAPPDATA || join(home, 'AppData/Local'), 'Programs/Outask');
+  if (platform === 'darwin') return join(home, 'Library/Application Support/Outask');
+  return join(home, '.local/share/outask');
+}
+
+export function configPath(env = process.env) {
+  return env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, 'outask/config.json') : join(applicationRoot(env), 'config.json');
+}
+
+export function cacheRoot(env = process.env) {
+  return env.XDG_CACHE_HOME ? join(env.XDG_CACHE_HOME, 'outask/cache') : join(applicationRoot(env), 'cache');
+}

package/src/pagination.mjs

@@ -0,0 +1,30 @@
+import { fail } from './errors.mjs';
+import { projectFields } from './fields.mjs';
+import { responseBytes } from './limits.mjs';
+import { jsonBytes } from './response.mjs';
+
+export function updatePage(page) {
+  page.hasMore = page.offset + page.tasks.length < page.total;
+  page.nextOffset = page.hasMore ? page.offset + page.tasks.length : null;
+  return page;
+}
+
+export function taskPage(records, { offset, limit, stores, fields, total = records.length, recordsOffset = offset }) {
+  const page = updatePage({ tasks: [], total, offset, limit, stores, fields });
+  if (jsonBytes(page) + 1 > responseBytes) {
+    fail('OUTPUT_TOO_LARGE', 'list metadata exceeds 32 KiB; select fewer --fields or stores');
+  }
+  for (let index = recordsOffset; index < records.length && page.tasks.length < limit; index++) {
+    page.tasks.push(projectFields(records[index], fields));
+    updatePage(page);
+    if (jsonBytes(page) + 1 > responseBytes) {
+      page.tasks.pop();
+      updatePage(page);
+      if (!page.tasks.length) {
+        fail('OUTPUT_TOO_LARGE', `task ${records[index].id} cannot fit in a 32 KiB page; select fewer --fields`);
+      }
+      break;
+    }
+  }
+  return page;
+}