ai-dev-worklog 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to AI Dev Worklog are recorded here.
+
+## 0.5.0 - 2026-06-07
+
+- Add `--intent` for recording the task goal in local worklog output.
+- Include declared intent in Markdown and continuation prompt output.
+- Set `schemaVersion` to `0.3` and expand the JSON Schema for provided CLI intent.
+- Add npm package metadata and public install guidance.
+- Add public launch and application draft notes for early open-source feedback.
+
+## 0.4.0 - 2026-06-06
+
+- Add GitHub Actions CI for install, build, and test validation.
+- Add a formal JSON Schema for `latest.json` at `schema/worklog.schema.json`.
+- Add this changelog as a lightweight release history.
+- Refresh the README roadmap and demo flow around current local CLI capabilities.
+
+## 0.3.0
+
+- Add `.ai-dev-worklog/continue-prompt.md`.
+- Add continuation prompt rendering from the structured worklog scan.
+- Keep `schemaVersion` at `0.2` because the JSON output structure did not change.
+- Update examples and documentation for the continuation prompt output.
+
+## 0.2.0
+
+- Define the structured worklog JSON output shape.
+- Set `schemaVersion` to `0.2`.
+- Preserve raw git command output under `evidence.git`.
+- Add unified observed file changes, validation status, risk signals, and next steps.
+- Update README and examples for the structured schema.
+
+## 0.1.0
+
+- Add the local TypeScript CLI core.
+- Scan local git evidence from `git status --porcelain`, `git diff --stat`, and `git diff --name-status`.
+- Write `.ai-dev-worklog/latest.md` and `.ai-dev-worklog/latest.json`.
+- Keep all scan output local to the repository.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alexan780
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# AI Dev Worklog
+
+[![CI](https://github.com/alexan780/ai-dev-worklog/actions/workflows/ci.yml/badge.svg)](https://github.com/alexan780/ai-dev-worklog/actions/workflows/ci.yml)
+
+A local CLI that turns git evidence into a readable AI development worklog.
+
+AI Dev Worklog scans the current git repository and writes a Markdown report, a JSON report, and a continuation prompt. It is useful when an AI-assisted coding session needs a local, reviewable record of what changed, what the task goal was, and how to continue.
+
+The CLI is intentionally small and local-first: it reads git evidence, writes files under `.ai-dev-worklog/`, and keeps the output on your machine.
+
+## What It Does Now
+
+`ai-dev-worklog scan` records:
+
+- optional declared intent from `--intent`
+- changed files from `git status --porcelain`
+- tracked file changes from `git diff --name-status`
+- diff summary from `git diff --stat`
+- raw command output for the scanned git commands
+- structured JSON fields for evidence, observed changes, validation status, risk signals, and next steps
+- a continuation prompt file for the next development session
+
+## Quick Start
+
+Run once with `npx`:
+
+```bash
+npx ai-dev-worklog scan
+```
+
+Add a task goal for the next session:
+
+```bash
+npx ai-dev-worklog scan --intent "Prepare the repository for an open-source release"
+```
+
+Install globally:
+
+```bash
+npm install -g ai-dev-worklog
+ai-dev-worklog scan --intent "Review local changes before opening a pull request"
+```
+
+Run from source:
+
+```bash
+git clone https://github.com/alexan780/ai-dev-worklog.git
+cd ai-dev-worklog
+npm ci
+npm run build
+node dist/index.js scan --intent "Verify the local CLI from source"
+```
+
+## Local Output
+
+Running `ai-dev-worklog scan` writes:
+
+```text
+.ai-dev-worklog/
+  latest.md
+  latest.json
+  continue-prompt.md
+```
+
+`latest.md` is the human-readable report.
+`latest.json` is the machine-readable scan result. It uses a structured worklog schema that separates declared intent, git evidence, observed changes, validation status, risk signals, and next steps. The formal JSON Schema is available at [`schema/worklog.schema.json`](schema/worklog.schema.json).
+`continue-prompt.md` is a prompt-oriented summary for continuing the development session.
+
+Example output is available in [`examples/basic-worklog`](examples/basic-worklog).
+
+Example summary:
+
+```text
+## Summary
+
+- Git status entries: 2
+- Git diff name-status entries: 2
+- Changed files: 2
+- Working tree has changes: yes
+- Validation: not_recorded
+- Risk signals: 0
+- Declared intent: Prepare the repository for an open-source release
+```
+
+## What The CLI Scans
+
+The local CLI reads these git commands:
+
+```bash
+git status --porcelain
+git diff --stat
+git diff --name-status
+```
+
+The scan uses local git evidence as the source of truth for observed code changes.
+
+The CLI does not read chat windows, call AI APIs, upload code, or integrate with Codex App, Claude Code, Cursor, or MCP tools.
+
+## Privacy And Data Flow
+
+AI Dev Worklog runs locally in the git repository where you call it.
+
+- It runs local git commands.
+- It writes local files under `.ai-dev-worklog/`.
+- It does not upload source code or generated worklogs.
+- It does not require an API key.
+
+## Why This Exists
+
+When context breaks, tools switch, or a task becomes long, it can be hard to answer:
+
+- What files actually changed?
+- What git evidence is available?
+- What still needs checking?
+- How should the next session continue?
+
+AI Dev Worklog turns AI-assisted coding sessions into local, reviewable development records.
+
+## Local Development
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+Build the TypeScript CLI:
+
+```bash
+npm run build
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Run a local scan:
+
+```bash
+node dist/index.js scan --intent "Validate local development output"
+```
+
+Generated build output goes to `dist/`.
+Generated worklog output goes to `.ai-dev-worklog/`.
+
+GitHub Actions runs the same install, build, and test checks on pushes to `main` and on pull requests.
+
+## What It Records
+
+The CLI records observed local git evidence.
+
+Current output includes:
+
+- optional declared intent from the CLI
+- changed files from `git status --porcelain`
+- tracked file changes from `git diff --name-status`
+- diff summary from `git diff --stat`
+- raw command output for the scanned git commands
+- a JSON worklog schema with declared intent, evidence, observed changes, validation status, risk signals, and next steps
+- a continuation prompt file with changed files, command results, risk signals, remaining checks, and suggested next steps
+
+Future versions may add command history and validation evidence.
+
+## What It Is
+
+- Local first
+- Evidence before summary
+- Human-readable Markdown
+- Machine-readable JSON
+- Minimal dependencies
+
+## Roadmap
+
+### Released
+
+#### v0.1 - Local Core
+
+- Scan the current git repository
+- Record changed files from local git evidence
+- Generate `latest.md` and `latest.json`
+- Keep all data local
+
+#### v0.2 - Worklog Schema
+
+- Define a stable JSON structure for AI coding worklogs
+- Separate declared intent from observed evidence
+- Add unified observed file changes
+- Add validation status and basic risk signals
+
+#### v0.3 - Continuation Prompt
+
+- Generate a continuation prompt for the next development session
+- Keep git evidence as the source of truth for observed code changes
+
+#### v0.4 - Open-source Readiness
+
+- Add GitHub Actions CI
+- Add a formal JSON Schema file for `latest.json`
+- Add a changelog and release history
+- Improve README demo flow and roadmap clarity
+
+#### v0.5 - Declared Intent
+
+- Add `--intent` for recording the task goal in local worklog output
+- Include declared intent in Markdown and continuation prompt output
+- Prepare npm metadata and public installation paths
+
+### Future Work
+
+- Command history and validation evidence
+- Optional workflow guides for AI coding tools
+
+## Status
+
+This project is in early development.
+The CLI scans a git repository and generates a local Markdown worklog, a structured JSON scan result, and a continuation prompt.
+
+The next milestones focus on strengthening the local CLI contract before adding optional workflow integrations.

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+export interface GitCommandResult {
+    command: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface StatusEntry {
+    indexStatus: string;
+    workingTreeStatus: string;
+    path: string;
+    previousPath?: string;
+    raw: string;
+}
+export interface NameStatusEntry {
+    status: string;
+    path: string;
+    previousPath?: string;
+    raw: string;
+}
+export type ObservedFileStatus = "modified" | "added" | "deleted" | "renamed" | "copied" | "untracked" | "unknown";
+export interface ToolInfo {
+    name: string;
+    version: string;
+    command: string;
+}
+export interface RepositoryInfo {
+    cwd: string;
+    gitRoot: string;
+}
+export interface DeclaredIntent {
+    status: "not_provided" | "provided";
+    source: "not_provided" | "cli_option";
+    summary: string | null;
+}
+export interface ScanOptions {
+    intent?: string;
+}
+export interface ObservedFileChange {
+    path: string;
+    previousPath: string | null;
+    status: ObservedFileStatus;
+    sources: string[];
+}
+export interface ValidationRecord {
+    status: "not_recorded";
+    commands: [];
+}
+export interface RiskSignal {
+    kind: "untracked_files" | "deleted_files" | "renamed_files";
+    severity: "info" | "warning";
+    message: string;
+    paths: string[];
+}
+export interface RiskSignals {
+    items: RiskSignal[];
+}
+export interface NextSteps {
+    items: [];
+    continuationPrompt: string;
+}
+export interface WorklogScan {
+    schemaVersion: "0.3";
+    generatedAt: string;
+    tool: ToolInfo;
+    repository: RepositoryInfo;
+    declaredIntent: DeclaredIntent;
+    summary: {
+        statusEntryCount: number;
+        diffNameStatusEntryCount: number;
+        changedFileCount: number;
+        hasWorkingTreeChanges: boolean;
+        validationStatus: ValidationRecord["status"];
+        riskSignalCount: number;
+    };
+    evidence: {
+        git: {
+            statusPorcelain: GitCommandResult;
+            diffStat: GitCommandResult;
+            diffNameStatus: GitCommandResult;
+        };
+    };
+    observedChanges: {
+        statusEntries: StatusEntry[];
+        diffNameStatusEntries: NameStatusEntry[];
+        files: ObservedFileChange[];
+    };
+    validation: ValidationRecord;
+    riskSignals: RiskSignals;
+    nextSteps: NextSteps;
+}
+export declare function parseStatusPorcelain(output: string): StatusEntry[];
+export declare function parseNameStatus(output: string): NameStatusEntry[];
+export declare function buildObservedFiles(statusEntries: StatusEntry[], diffNameStatusEntries: NameStatusEntry[]): ObservedFileChange[];
+export declare function buildRiskSignals(files: ObservedFileChange[]): RiskSignals;
+export declare function scanRepository(cwd?: string, options?: ScanOptions): Promise<WorklogScan>;
+export declare function writeScanOutputs(scan: WorklogScan): Promise<{
+    markdownPath: string;
+    jsonPath: string;
+    continuePromptPath: string;
+}>;
+export declare function renderMarkdown(scan: WorklogScan): string;
+export declare function renderContinuePrompt(scan: WorklogScan): string;
+export declare function runCli(argv?: string[], cwd?: string): Promise<number>;