zerg-status 0.1.0 → 1.1.0

package/bin/zerg-status.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function init(name?: string): void;

package/dist/commands/init.js

@@ -0,0 +1,8 @@
+import { createSession } from '../state.js';
+import { formatSessionOutput } from '../output.js';
+import { validateName } from '../validate.js';
+export function init(name) {
+    const validatedName = name ? validateName(name) : undefined;
+    const { sessionId, name: sessionName } = createSession(validatedName);
+    console.log(formatSessionOutput(sessionId, sessionName));
+}

package/dist/commands/now.d.ts

@@ -0,0 +1 @@
+export declare function nowCommand(sessionId: string, text: string): void;

package/dist/commands/now.js

@@ -0,0 +1,8 @@
+import { setNow } from '../state.js';
+import { validateNow } from '../validate.js';
+import { formatStatusOutput } from '../output.js';
+export function nowCommand(sessionId, text) {
+    const validText = validateNow(text);
+    const state = setNow(sessionId, validText);
+    console.log(formatStatusOutput(state));
+}

package/dist/commands/state.d.ts

@@ -0,0 +1 @@
+export declare function stateCommand(sessionId: string, stateValue: string, question?: string): void;

package/dist/commands/state.js

@@ -0,0 +1,8 @@
+import { setState } from '../state.js';
+import { validateState } from '../validate.js';
+import { formatStatusOutput } from '../output.js';
+export function stateCommand(sessionId, stateValue, question) {
+    const validState = validateState(stateValue);
+    const state = setState(sessionId, validState, question);
+    console.log(formatStatusOutput(state));
+}

package/dist/commands/summary.d.ts

@@ -0,0 +1 @@
+export declare function summaryCommand(sessionId: string, text: string): void;

package/dist/commands/summary.js

@@ -0,0 +1,8 @@
+import { setSummary } from '../state.js';
+import { validateSummary } from '../validate.js';
+import { formatStatusOutput } from '../output.js';
+export function summaryCommand(sessionId, text) {
+    const validText = validateSummary(text);
+    const state = setSummary(sessionId, validText);
+    console.log(formatStatusOutput(state));
+}

package/dist/commands/task.d.ts

@@ -0,0 +1 @@
+export declare function taskCommand(sessionId: string, action: string, taskDescription?: string): void;

package/dist/commands/task.js

@@ -0,0 +1,25 @@
+import { addTask, updateTaskStatus, clearTasks } from '../state.js';
+import { validateTaskStatus } from '../validate.js';
+import { formatStatusOutput } from '../output.js';
+export function taskCommand(sessionId, action, taskDescription) {
+    if (action === 'clear') {
+        const state = clearTasks(sessionId);
+        console.log(formatStatusOutput(state));
+        return;
+    }
+    if (action === 'add') {
+        if (!taskDescription) {
+            throw new Error('Task description required for "add" action');
+        }
+        const state = addTask(sessionId, taskDescription, 'todo');
+        console.log(formatStatusOutput(state));
+        return;
+    }
+    // action is a task status: todo, doing, done
+    const status = validateTaskStatus(action);
+    if (!taskDescription) {
+        throw new Error('Task description required');
+    }
+    const state = updateTaskStatus(sessionId, taskDescription, status);
+    console.log(formatStatusOutput(state));
+}

package/dist/commands/tasks.d.ts

@@ -0,0 +1 @@
+export declare function tasksCommand(sessionId: string, action: string, taskDescriptions: string[]): void;

package/dist/commands/tasks.js

@@ -0,0 +1,9 @@
+import { setTasks } from '../state.js';
+import { formatStatusOutput } from '../output.js';
+export function tasksCommand(sessionId, action, taskDescriptions) {
+    if (action !== 'set') {
+        throw new Error(`Unknown tasks action: ${action}. Use "tasks set <task1> <task2> ..."`);
+    }
+    const state = setTasks(sessionId, taskDescriptions);
+    console.log(formatStatusOutput(state));
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * zerg-status - Progress reporting CLI for Zerg dashboard
+ *
+ * Usage:
+ *   npx zerg-status init "Session Name"            # Initialize session with name
+ *   npx zerg-status init                           # Initialize session, outputs ZERG_SESSION:<id>
+ *   npx zerg-status -s <id> state work             # Set state to work/ask/done
+ *   npx zerg-status -s <id> state ask "Question?"  # Set state to ask with a question
+ *   npx zerg-status -s <id> now "Headline"         # Set current activity headline
+ *   npx zerg-status -s <id> summary "Details"      # Set detailed summary
+ *   npx zerg-status -s <id> task add "Task"        # Add a task
+ *   npx zerg-status -s <id> task doing "Task"      # Mark task as in progress
+ *   npx zerg-status -s <id> task done "Task"       # Mark task as complete
+ *   npx zerg-status -s <id> task clear             # Clear all tasks
+ *   npx zerg-status -s <id> tasks set "A" "B" "C"  # Replace all tasks
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * zerg-status - Progress reporting CLI for Zerg dashboard
+ *
+ * Usage:
+ *   npx zerg-status init "Session Name"            # Initialize session with name
+ *   npx zerg-status init                           # Initialize session, outputs ZERG_SESSION:<id>
+ *   npx zerg-status -s <id> state work             # Set state to work/ask/done
+ *   npx zerg-status -s <id> state ask "Question?"  # Set state to ask with a question
+ *   npx zerg-status -s <id> now "Headline"         # Set current activity headline
+ *   npx zerg-status -s <id> summary "Details"      # Set detailed summary
+ *   npx zerg-status -s <id> task add "Task"        # Add a task
+ *   npx zerg-status -s <id> task doing "Task"      # Mark task as in progress
+ *   npx zerg-status -s <id> task done "Task"       # Mark task as complete
+ *   npx zerg-status -s <id> task clear             # Clear all tasks
+ *   npx zerg-status -s <id> tasks set "A" "B" "C"  # Replace all tasks
+ */
+import { init } from './commands/init.js';
+import { stateCommand } from './commands/state.js';
+import { nowCommand } from './commands/now.js';
+import { summaryCommand } from './commands/summary.js';
+import { taskCommand } from './commands/task.js';
+import { tasksCommand } from './commands/tasks.js';
+import { validateSessionId, ValidationError } from './validate.js';
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    let sessionId;
+    let command = 'help';
+    const commandArgs = [];
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === '-s' || arg === '--session') {
+            sessionId = args[i + 1];
+            i += 2;
+            continue;
+        }
+        if (!command || command === 'help') {
+            command = arg;
+            i++;
+            continue;
+        }
+        commandArgs.push(arg);
+        i++;
+    }
+    return { sessionId, command, args: commandArgs };
+}
+function printHelp() {
+    console.log(`
+zerg-status - Progress reporting CLI for Zerg dashboard
+
+COMMANDS:
+  init "Session Name"            Initialize new session with name (outputs ZERG_SESSION:<id>:<name>)
+  init                           Initialize new session (outputs ZERG_SESSION:<id>)
+
+  -s <id> state <work|ask|done>  Set session state
+  -s <id> state ask "Question?"  Set state to ask with a question
+  -s <id> state done             Set state to done
+
+  -s <id> now "Headline"         Set current activity (max 50 chars)
+  -s <id> summary "Details"      Set detailed summary (max 500 chars)
+
+  -s <id> task add "Task"        Add a task (status: todo)
+  -s <id> task doing "Task"      Mark task as in progress
+  -s <id> task done "Task"       Mark task as complete
+  -s <id> task todo "Task"       Mark task as pending
+  -s <id> task clear             Clear all tasks
+
+  -s <id> tasks set "A" "B" "C"  Replace all tasks (max 20 tasks)
+
+EXAMPLES:
+  npx zerg-status init "Fix auth bug"
+  # ZERG_SESSION:f7a3b2c1:Fix auth bug
+
+  npx zerg-status -s f7a3b2c1 state work
+  npx zerg-status -s f7a3b2c1 now "Writing unit tests"
+  npx zerg-status -s f7a3b2c1 tasks set "Task 1" "Task 2" "Task 3"
+  npx zerg-status -s f7a3b2c1 task doing "Task 1"
+  npx zerg-status -s f7a3b2c1 task done "Task 1"
+  npx zerg-status -s f7a3b2c1 state done
+
+OUTPUT:
+  init outputs:    ZERG_SESSION:<session_id>[:<name>]
+  all others:      ZERG_STATUS:<full_json_state>
+`);
+}
+function main() {
+    try {
+        const { sessionId, command, args } = parseArgs(process.argv);
+        switch (command) {
+            case 'init': {
+                const name = args.join(' ') || undefined;
+                init(name);
+                break;
+            }
+            case 'state': {
+                const validSessionId = validateSessionId(sessionId);
+                const [stateValue, ...rest] = args;
+                if (!stateValue) {
+                    throw new ValidationError('State value required. Use: work, ask, or done');
+                }
+                const question = stateValue === 'ask' ? rest.join(' ') : undefined;
+                stateCommand(validSessionId, stateValue, question);
+                break;
+            }
+            case 'now': {
+                const validSessionId = validateSessionId(sessionId);
+                const text = args.join(' ');
+                if (!text) {
+                    throw new ValidationError('Now text required');
+                }
+                nowCommand(validSessionId, text);
+                break;
+            }
+            case 'summary': {
+                const validSessionId = validateSessionId(sessionId);
+                const text = args.join(' ');
+                if (!text) {
+                    throw new ValidationError('Summary text required');
+                }
+                summaryCommand(validSessionId, text);
+                break;
+            }
+            case 'task': {
+                const validSessionId = validateSessionId(sessionId);
+                const [action, ...rest] = args;
+                if (!action) {
+                    throw new ValidationError('Task action required. Use: add, doing, done, todo, or clear');
+                }
+                const taskDescription = rest.join(' ') || undefined;
+                taskCommand(validSessionId, action, taskDescription);
+                break;
+            }
+            case 'tasks': {
+                const validSessionId = validateSessionId(sessionId);
+                const [action, ...taskDescriptions] = args;
+                if (!action) {
+                    throw new ValidationError('Tasks action required. Use: set');
+                }
+                tasksCommand(validSessionId, action, taskDescriptions);
+                break;
+            }
+            case 'help':
+            case '--help':
+            case '-h':
+                printHelp();
+                break;
+            default:
+                console.error(`Unknown command: ${command}`);
+                console.error('Run "npx zerg-status help" for usage');
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        if (err instanceof ValidationError) {
+            console.error(`Error: ${err.message}`);
+        }
+        else if (err instanceof Error) {
+            console.error(`Error: ${err.message}`);
+        }
+        else {
+            console.error('Unknown error');
+        }
+        process.exit(1);
+    }
+}
+main();

package/dist/output.d.ts

@@ -0,0 +1,3 @@
+import type { ZergState } from './types.js';
+export declare function formatSessionOutput(sessionId: string, name?: string): string;
+export declare function formatStatusOutput(state: ZergState): string;

package/dist/output.js

@@ -0,0 +1,9 @@
+export function formatSessionOutput(sessionId, name) {
+    if (name) {
+        return `ZERG_SESSION:${sessionId}:${name}`;
+    }
+    return `ZERG_SESSION:${sessionId}`;
+}
+export function formatStatusOutput(state) {
+    return `ZERG_STATUS:${JSON.stringify(state)}`;
+}

package/dist/state.d.ts

@@ -0,0 +1,16 @@
+import type { ZergState, State, TaskStatus } from './types.js';
+export declare function generateSessionId(): string;
+export declare function createSession(name?: string): {
+    sessionId: string;
+    name?: string;
+};
+export declare function loadState(sessionId: string): ZergState;
+export declare function saveState(state: ZergState): void;
+export declare function updateState(sessionId: string, updates: Partial<ZergState>): ZergState;
+export declare function setState(sessionId: string, newState: State, question?: string): ZergState;
+export declare function setNow(sessionId: string, now: string): ZergState;
+export declare function setSummary(sessionId: string, summary: string): ZergState;
+export declare function addTask(sessionId: string, taskDescription: string, status?: TaskStatus): ZergState;
+export declare function updateTaskStatus(sessionId: string, taskDescription: string, status: TaskStatus): ZergState;
+export declare function clearTasks(sessionId: string): ZergState;
+export declare function setTasks(sessionId: string, taskDescriptions: string[]): ZergState;

package/dist/state.js

@@ -0,0 +1,115 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import { DEFAULT_STATE } from './types.js';
+import { validateTaskCount, validateTask } from './validate.js';
+const STATE_DIR = path.join(os.homedir(), '.zerg-status');
+function ensureStateDir() {
+    if (!fs.existsSync(STATE_DIR)) {
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+    }
+}
+function getStatePath(sessionId) {
+    return path.join(STATE_DIR, `${sessionId}.json`);
+}
+export function generateSessionId() {
+    return crypto.randomBytes(4).toString('hex');
+}
+export function createSession(name) {
+    ensureStateDir();
+    const sessionId = generateSessionId();
+    const state = {
+        session: sessionId,
+        name,
+        ...DEFAULT_STATE,
+    };
+    fs.writeFileSync(getStatePath(sessionId), JSON.stringify(state, null, 2));
+    return { sessionId, name };
+}
+export function loadState(sessionId) {
+    ensureStateDir();
+    const statePath = getStatePath(sessionId);
+    if (!fs.existsSync(statePath)) {
+        // Create default state for this session
+        const state = {
+            session: sessionId,
+            ...DEFAULT_STATE,
+        };
+        fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+        return state;
+    }
+    const data = fs.readFileSync(statePath, 'utf-8');
+    return JSON.parse(data);
+}
+export function saveState(state) {
+    ensureStateDir();
+    const statePath = getStatePath(state.session);
+    // Atomic write: write to temp file first, then rename
+    const tempPath = `${statePath}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(state, null, 2));
+    fs.renameSync(tempPath, statePath);
+}
+export function updateState(sessionId, updates) {
+    const state = loadState(sessionId);
+    Object.assign(state, updates);
+    saveState(state);
+    return state;
+}
+export function setState(sessionId, newState, question) {
+    const state = loadState(sessionId);
+    state.state = newState;
+    if (newState === 'ask' && question) {
+        state.question = question;
+    }
+    else if (newState !== 'ask') {
+        delete state.question;
+    }
+    saveState(state);
+    return state;
+}
+export function setNow(sessionId, now) {
+    return updateState(sessionId, { now });
+}
+export function setSummary(sessionId, summary) {
+    return updateState(sessionId, { summary });
+}
+export function addTask(sessionId, taskDescription, status = 'todo') {
+    const state = loadState(sessionId);
+    validateTask(taskDescription);
+    validateTaskCount(state.tasks.length + 1);
+    state.tasks.push({ task: taskDescription, status });
+    saveState(state);
+    return state;
+}
+export function updateTaskStatus(sessionId, taskDescription, status) {
+    const state = loadState(sessionId);
+    // Find task by exact match or partial match
+    let task = state.tasks.find(t => t.task === taskDescription);
+    if (!task) {
+        // Try partial match
+        task = state.tasks.find(t => t.task.toLowerCase().includes(taskDescription.toLowerCase()));
+    }
+    if (!task) {
+        // Add new task with the given status
+        validateTask(taskDescription);
+        validateTaskCount(state.tasks.length + 1);
+        state.tasks.push({ task: taskDescription, status });
+    }
+    else {
+        task.status = status;
+    }
+    saveState(state);
+    return state;
+}
+export function clearTasks(sessionId) {
+    return updateState(sessionId, { tasks: [] });
+}
+export function setTasks(sessionId, taskDescriptions) {
+    validateTaskCount(taskDescriptions.length);
+    const tasks = taskDescriptions.map(task => {
+        validateTask(task);
+        return { task, status: 'todo' };
+    });
+    return updateState(sessionId, { tasks });
+}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+export type State = 'work' | 'ask' | 'done';
+export type TaskStatus = 'todo' | 'doing' | 'done';
+export interface Task {
+    task: string;
+    status: TaskStatus;
+}
+export interface ZergState {
+    session: string;
+    name?: string;
+    state: State;
+    now: string;
+    summary: string;
+    tasks: Task[];
+    question?: string;
+}
+export declare const DEFAULT_STATE: Omit<ZergState, 'session'>;

package/dist/types.js

@@ -0,0 +1,6 @@
+export const DEFAULT_STATE = {
+    state: 'work',
+    now: '',
+    summary: '',
+    tasks: [],
+};

package/dist/validate.d.ts

@@ -0,0 +1,20 @@
+import type { State, TaskStatus } from './types.js';
+export declare const VALID_STATES: State[];
+export declare const VALID_TASK_STATUSES: TaskStatus[];
+export declare const MAX_NOW_LENGTH = 50;
+export declare const MAX_SUMMARY_LENGTH = 500;
+export declare const MAX_TASK_LENGTH = 200;
+export declare const MAX_TASKS = 20;
+export declare const MAX_NAME_LENGTH = 60;
+export declare const MAX_NAME_WORDS = 6;
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+export declare function validateState(state: string): State;
+export declare function validateTaskStatus(status: string): TaskStatus;
+export declare function validateNow(now: string): string;
+export declare function validateSummary(summary: string): string;
+export declare function validateTask(task: string): string;
+export declare function validateTaskCount(count: number): void;
+export declare function validateSessionId(sessionId: string | undefined): string;
+export declare function validateName(name: string): string;

package/dist/validate.js

@@ -0,0 +1,65 @@
+export const VALID_STATES = ['work', 'ask', 'done'];
+export const VALID_TASK_STATUSES = ['todo', 'doing', 'done'];
+export const MAX_NOW_LENGTH = 50;
+export const MAX_SUMMARY_LENGTH = 500;
+export const MAX_TASK_LENGTH = 200;
+export const MAX_TASKS = 20;
+export const MAX_NAME_LENGTH = 60;
+export const MAX_NAME_WORDS = 6;
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+export function validateState(state) {
+    if (!VALID_STATES.includes(state)) {
+        throw new ValidationError(`Invalid state: ${state}. Must be one of: ${VALID_STATES.join(', ')}`);
+    }
+    return state;
+}
+export function validateTaskStatus(status) {
+    if (!VALID_TASK_STATUSES.includes(status)) {
+        throw new ValidationError(`Invalid task status: ${status}. Must be one of: ${VALID_TASK_STATUSES.join(', ')}`);
+    }
+    return status;
+}
+export function validateNow(now) {
+    if (now.length > MAX_NOW_LENGTH) {
+        throw new ValidationError(`Now text too long (${now.length} chars). Max ${MAX_NOW_LENGTH} chars.`);
+    }
+    return now;
+}
+export function validateSummary(summary) {
+    if (summary.length > MAX_SUMMARY_LENGTH) {
+        throw new ValidationError(`Summary too long (${summary.length} chars). Max ${MAX_SUMMARY_LENGTH} chars.`);
+    }
+    return summary;
+}
+export function validateTask(task) {
+    if (task.length > MAX_TASK_LENGTH) {
+        throw new ValidationError(`Task too long (${task.length} chars). Max ${MAX_TASK_LENGTH} chars.`);
+    }
+    return task;
+}
+export function validateTaskCount(count) {
+    if (count > MAX_TASKS) {
+        throw new ValidationError(`Too many tasks (${count}). Max ${MAX_TASKS} tasks.`);
+    }
+}
+export function validateSessionId(sessionId) {
+    if (!sessionId) {
+        throw new ValidationError('Session ID required. Use -s <id> flag or run "npx zerg-status init" first.');
+    }
+    return sessionId;
+}
+export function validateName(name) {
+    if (name.length > MAX_NAME_LENGTH) {
+        throw new ValidationError(`Name too long (${name.length} chars). Max ${MAX_NAME_LENGTH} chars.`);
+    }
+    const wordCount = name.trim().split(/\s+/).length;
+    if (wordCount > MAX_NAME_WORDS) {
+        throw new ValidationError(`Name has too many words (${wordCount}). Max ${MAX_NAME_WORDS} words.`);
+    }
+    return name;
+}

package/package.json

@@ -1,38 +1,27 @@
 {
   "name": "zerg-status",
-  "version": "0.1.0",
-  "description": "CLI for AI coding agents to report status to a central store",
+  "version": "1.1.0",
+  "description": "Progress reporting CLI for Zerg dashboard",
   "type": "module",
   "bin": {
-    "zerg": "./dist/cli.js"
+    "zerg-status": "./bin/zerg-status.js"
   },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "files": [
+    "bin",
     "dist"
   ],
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "ai",
-    "agent",
-    "status",
-    "cli",
-    "devin",
-    "claude",
-    "coding-agent"
-  ],
-  "author": "Exa Labs",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/exa-labs/zerg"
+    "dev": "tsc --watch",
+    "test": "node --test dist/*.test.js"
   },
   "engines": {
     "node": ">=18"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^20.10.0",
     "typescript": "^5.3.0"
   }
 }