outask 1.6.0 → 1.7.0

package/README.md

@@ -1,48 +1,39 @@
-# Install Outask with npm
+# Outask
 
-Requires Node.js 22.23.3 or later and npm on PATH. Supports Linux x64,
-macOS Apple silicon and native Windows x64. npm creates both `outask` and
-`tasks` command entries in its global prefix. Ensure that prefix's command
-directory is on PATH; open a fresh terminal and restart your MCP client.
+Outask is a lightweight task tracker that keeps tasks in readable JSON alongside your project code. Use its CLI from your terminal, or connect local AI agents through the optional MCP adapter.
+
+## Install
+
+Requires Node.js 22.23.3 or later and npm on PATH.
 
 ```sh
 npm install -g outask
 outask --version
-outask create --title "Write release notes"
-outask list --format table
 ```
 
-Run create/list from your project directory. npm installation needs no
-application installer, shell-profile modification or administrator privileges
-when your Node provider supplies a writable global prefix. Select one active
-installation channel: remove archive command links with that archive's installer
-before switching to npm; check `command -v outask` (POSIX) or `where.exe outask`
-(Windows) to confirm which command is selected.
+## CLI quick start
+
+Run from your project directory. Replace `1` with the ID returned by `create`.
 
 ```sh
-npm update -g outask
-npm uninstall -g outask
+outask create --title "Write release notes"
+outask list
+outask get 1
+outask update 1 --title "Review release notes"
+outask transition 1 --status done
 ```
 
-npm owns application files and command shims. Its uninstall removes those files;
-project records, installed skills, application configuration and cache remain.
-Remove a Git hook with `outask hook --remove` before uninstalling if installed;
-remove the MCP entry in your client when no longer needed. Do not delete live
-coordination files. Let active writes finish; existing MCP sessions may retain
-loaded code until the client restarts them normally. Archive installer update
-commands do not update npm installations. `outask update` edits a task.
+See the [operator reference](https://github.com/henryh/outask/blob/main/app/README.md) for project selection, task fields and configured statuses.
 
 ## Connect MCP
 
-Use `outask` with argument `mcp` on Linux/macOS:
+Configure your MCP client to run `outask mcp`. Tool calls select your repository with an absolute `project_path`. See [MCP setup](https://github.com/henryh/outask/blob/main/app/mcp/README.md) for client configuration.
+
+## Update or remove
 
 ```sh
-codex mcp add outask -- outask mcp
+npm update -g outask
+npm uninstall -g outask
 ```
 
-On Windows, use your client's documented npm command-shim support, or configure
-`node` with the absolute global package `bin/outask` path and argument `mcp`.
-Find the package directory with `npm root -g`. Tool calls still select the
-repository using an absolute `project_path`.
-
-See [MCP setup](https://github.com/henryh/outask/blob/main/app/mcp/README.md) and [operator commands](https://github.com/henryh/outask/blob/main/app/README.md).
+Uninstall removes the npm package and its commands; project tasks, skills, configuration and cache remain. See [installation and updates](https://github.com/henryh/outask/blob/main/app/README.md#installation-and-updates) for lifecycle details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outask",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Outask CLI for repository-local JSON task tracking",
   "author": "Henry <me@henrydev.me>",
   "license": "AGPL-3.0-only",

package/src/create.mjs

@@ -9,7 +9,7 @@ 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 { openProject, projectRelative, retainedFiles, serviceFile } from './stores.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);
@@ -59,9 +59,10 @@ function readActive(project, target, fingerprints) {
       source = text;
       count = 0;
     }
-    for (const { value: record } of records) {
+    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 ?? [] });

package/src/input.mjs

@@ -123,6 +123,8 @@ export function* arrayRecords(source, label) {
     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`);

package/src/stores.mjs

@@ -13,8 +13,8 @@ export const serviceFile = '.task-tracker.json';
 export const pendingFile = '.task-tracker.pending';
 
 export const standardStores = {
-  'active.json': { statuses: ['pending', 'in_progress', 'review'] },
-  'done.json': { statuses: ['done'] },
+  'active.json': { statuses: ['pending', 'in_progress', 'review'], missing_status: 'pending' },
+  'done.json': { statuses: ['done'], missing_status: 'done' },
   'archive.json': { statuses: ['cancelled'] },
 };
 export const defaultSearch = { mode: 'scan' };
@@ -102,6 +102,13 @@ function readConfig(path, budget, explicit, directory) {
       invalid(`store ${name} validate must be a boolean`);
     }
   }
+  for (const [name, store] of Object.entries(config.stores)) {
+    if (Object.hasOwn(store, 'missing_status') && (!isText(store.missing_status)
+      || !store.statuses.includes(store.missing_status)
+      || ['in_progress', 'review', ...(Array.isArray(config.working_statuses) ? config.working_statuses : [])].includes(store.missing_status))) {
+      invalid(`store ${name} missing_status must name a status in stores["${name}"].statuses that is not a working status; set a compatible missing_status manually`);
+    }
+  }
   const statuses = new Set(Object.values(config.stores).flatMap((store) => store.statuses));
   validateFieldRules(config.fields, path, statuses);
   for (const [name, store] of Object.entries(config.stores)) {
@@ -266,6 +273,19 @@ export function selectStoreFiles(project, { stores = [], group } = {}) {
   return { files: uninitialised ? [] : files, selectedGroup };
 }
 
+// Keep persisted records separate: inference is read-only until an actual mutation.
+export function effectiveRecord(task, project, file, label) {
+  if (!isObject(task) || Object.hasOwn(task, 'status')) return task;
+  const status = project.stores[file]?.missing_status;
+  if (status === undefined) {
+    const correction = project.config === undefined
+      ? 'set an explicit status on this record or configure its store with a non-working missing_status'
+      : `set stores["${file}"].missing_status in ${project.schemaPath} to a declared non-working status allowed by this store`;
+    fail('INVALID_STORE', `${label}: missing status; ${correction}; no fallback is configured for ${file}`);
+  }
+  return { ...task, status };
+}
+
 export function recordEntries(project, options = {}) {
   const { files, selectedGroup } = selectStoreFiles(project, options);
   const entries = (function* iterate() {
@@ -273,10 +293,20 @@ export function recordEntries(project, options = {}) {
     for (const file of files) {
       const path = join(project.directory, file);
       const { records: tasks } = readArray(path, project.budget);
-      for (const { value: task, index } of tasks) {
+      for (const { value, index } of tasks) {
         const label = `${path}[${index}]`;
-        if (!isObject(task) || !Number.isSafeInteger(task.id) || task.id <= 0 || !isText(task.title) || !isText(task.status)) {
-          fail('INVALID_STORE', `${label}: task needs a positive safe integer id and non-empty title/status strings`);
+        let task = value;
+        if (!isObject(task)) {
+          fail('INVALID_STORE', `${label}: task must be an object; correct this record to include id, title and status`);
+        }
+        if (Number.isSafeInteger(task.id) && task.id > 0 && isText(task.title)) task = effectiveRecord(task, project, file, label);
+        const invalidField = !Number.isSafeInteger(task.id) || task.id <= 0 ? 'id'
+          : !isText(task.title) ? 'title' : !isText(task.status) ? 'status' : undefined;
+        if (invalidField) {
+          const expected = invalidField === 'id' ? 'a positive safe integer unique across retained tasks'
+            : invalidField === 'status' ? "a non-empty string matching the project's workflow" : 'a non-empty string';
+          const problem = Object.hasOwn(task, invalidField) ? 'incompatible' : 'missing';
+          fail('INVALID_STORE', `${label}: ${problem} ${invalidField}; set ${invalidField} to ${expected}. Schema rules cannot waive this read minimum`);
         }
         validateTimestamp(task, label);
         const rules = project.stores[file];

package/src/transition.mjs

@@ -8,7 +8,7 @@ import { jsonBytes } from './response.mjs';
 import { fingerprint, knownCounter, readService, recoverMove, saveMove, serviceState, withProjectLock } from './service.mjs';
 import { changeFields } from './source.mjs';
 import { finishStore } from './storage-format.mjs';
-import { openProject, projectRelative, retainedFiles, serviceFile } from './stores.mjs';
+import { effectiveRecord, openProject, projectRelative, retainedFiles, serviceFile } from './stores.mjs';
 import { nextTimestamp, timestampValue, validateTimestamp } from './timestamps.mjs';
 import { scanProject, validateCycles, validateRecord } from './validation.mjs';
 
@@ -87,10 +87,11 @@ export function moveTask(projectPath, id, status, options, deleting, patch) {
         sources.set(file, selected);
         let previousEnd;
         for (const entry of records) {
-          const task = entry.value;
+          const task = rules.validate === false && rules.missing_status === undefined && entry.value.id !== id
+            ? entry.value : effectiveRecord(entry.value, project, file, `tasks/${file}`);
           selected.count++;
           if (found?.file === file && found.nextStart === undefined) found.nextStart = entry.start;
-          if (task.id === id) found = { file, task, start: entry.start, end: entry.end, previousEnd };
+          if (task.id === id) found = { file, task, persisted: entry.value, start: entry.start, end: entry.end, previousEnd };
           if (project.groups.get(task.status) === 'Active') {
             activeIds.add(task.id);
             if (rules.validate !== false) active.set(task.id, { blockers: task.blockers ?? [] });
@@ -132,8 +133,8 @@ export function moveTask(projectPath, id, status, options, deleting, patch) {
       if (jsonBytes(task) + 1 > responseBytes) fail('OUTPUT_TOO_LARGE', 'the complete transitioned task exceeds 32 KiB; shorten the record before moving it');
       if (!changed) return task;
       const selected = sources.get(found.file);
-      const fields = Object.fromEntries(Object.entries(task).filter(([key, value]) => !Object.hasOwn(found.task, key) || !same(value, found.task[key])));
-      const removed = Object.keys(found.task).filter((key) => !Object.hasOwn(task, key));
+      const fields = Object.fromEntries(Object.entries(task).filter(([key, value]) => !Object.hasOwn(found.persisted, key) || !same(value, found.persisted[key])));
+      const removed = Object.keys(found.persisted).filter((key) => !Object.hasOwn(task, key));
       const lineStart = selected.source.lastIndexOf(0x0a, found.start - 1) + 1;
       const prefix = selected.source.toString('utf8', lineStart, found.start);
       const indent = target === found.file

package/src/validation.mjs

@@ -4,7 +4,7 @@ import { applyFieldRules } from './field-rules.mjs';
 import { validateTimestamp } from './timestamps.mjs';
 import { projectBudget, readArray, readBuffer } from './input.mjs';
 import { knownCounter, readService, recoverMove, replaceFile, serviceState, withProjectLock } from './service.mjs';
-import { openProject, projectRelative, retainedFiles, serviceFile } from './stores.mjs';
+import { effectiveRecord, openProject, projectRelative, retainedFiles, serviceFile } from './stores.mjs';
 
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 const text = (value) => typeof value === 'string' && value.trim() !== '';
@@ -93,8 +93,9 @@ export function scanProject(projectPath, validate = true, schemaPath) {
       continue;
     }
     const { records } = readArray(join(project.directory, file), budget);
-    for (const { value: task, index } of records) {
+    for (const { value: persisted, index } of records) {
       const label = `tasks/${file}[${index}]`;
+      const task = project.stores[file]?.validate === false ? persisted : effectiveRecord(persisted, project, file, label);
       if (!object(task) || !id(task.id)) fail('INVALID_STORE', `${label}: id must be a positive safe integer on a task object`);
       if (seen.has(task.id)) fail('INVALID_STORE', `${label}: duplicate id ${task.id}; first seen at ${seen.get(task.id)}`);
       seen.set(task.id, label);