@chamba/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chamba contributors
+
+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,18 @@
+# @chamba/core
+
+Pure core logic for [chamba](https://github.com/thelord07/chamba): workspace scanner,
+plan generator + heuristic reviewer, git worktree manager, Obsidian context/vault
+writer, and a filesystem memory store.
+
+- **No Node APIs directly** — all OS access goes through ports (`FilesystemPort`,
+  `ProcessPort`, `ClockPort`), so it's testable and runtime-agnostic.
+- **No LLM** — chamba never calls a model.
+- Node implementations of the ports live in
+  [`@chamba/adapters`](https://www.npmjs.com/package/@chamba/adapters).
+
+Most users want the [`@chamba/mcp`](https://www.npmjs.com/package/@chamba/mcp) server,
+not this library directly.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+/**
+ * Time behind a port so date-dependent logic (plan filenames, vault notes) is
+ * testable and `@chamba/core` stays free of ambient `Date` calls.
+ */
+interface ClockPort {
+    now(): Date;
+    /** Current date as `YYYY-MM-DD`. */
+    today(): string;
+}
+
+/** A single entry returned when listing a directory. */
+interface DirEntry {
+    name: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+/**
+ * Filesystem access behind a port so `@chamba/core` never imports `node:fs`.
+ * Node implementation lives in `@chamba/adapters`; an in-memory implementation
+ * for tests lives in `@chamba/core/testing`.
+ */
+interface FilesystemPort {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    readDir(path: string): Promise<DirEntry[]>;
+    exists(path: string): Promise<boolean>;
+    /** Create a directory and any missing parents (recursive). */
+    mkdir(path: string): Promise<void>;
+    /** Remove a file or directory (recursive); a no-op if it doesn't exist. */
+    remove(path: string): Promise<void>;
+}
+
+interface Memory {
+    key: string;
+    content: string;
+    tags: string[];
+    /** ISO timestamp of first write. */
+    createdAt: string;
+    /** ISO timestamp of last write (set when the memory is appended to). */
+    updatedAt: string;
+    /** Path to the markdown file on disk. */
+    path: string;
+}
+interface RememberInput {
+    key: string;
+    content: string;
+    tags?: string[];
+}
+/**
+ * Persistent, human-editable memory across sessions. Implementations store one
+ * markdown file per memory (never JSON or a DB), so the user can read and edit
+ * them by hand.
+ */
+interface MemoryStore {
+    remember(input: RememberInput): Promise<Memory>;
+    recall(query: string): Promise<Memory[]>;
+}
+
+/** Directory (relative to root) where memories live. */
+declare const MEMORY_DIR = ".chamba/memory";
+/**
+ * Filesystem-backed `MemoryStore`. One markdown file per memory under
+ * `.chamba/memory/<slug>.md`, with YAML-ish frontmatter (key, tags, createdAt,
+ * updatedAt). Re-remembering an existing key appends a timestamped section
+ * instead of overwriting. Search is case-insensitive substring over key, tags
+ * and content.
+ */
+declare class FilesystemMemoryStore implements MemoryStore {
+    private readonly fs;
+    private readonly clock;
+    private readonly root;
+    constructor(fs: FilesystemPort, clock: ClockPort, root: string);
+    private dir;
+    private pathFor;
+    remember(input: RememberInput): Promise<Memory>;
+    recall(query: string): Promise<Memory[]>;
+    private read;
+}
+
+interface NoteFields {
+    title: string;
+    /** `YYYY-MM-DD`. */
+    date: string;
+    tags: string[];
+    /** Markdown body the model produced (summary, plan, decisions, etc.). */
+    body: string;
+}
+/** Turn a title into a filesystem- and Obsidian-friendly slug. */
+declare function slugify(title: string): string;
+/**
+ * Render a vault note: valid YAML frontmatter (parseable by Obsidian) followed
+ * by the model's markdown body. Override this template by passing your own body
+ * structure — chamba only owns the frontmatter and the title heading.
+ */
+declare function renderNote(fields: NoteFields): string;
+
+interface WriteNoteInput {
+    vaultPath: string;
+    title: string;
+    content: string;
+    /** Subfolder slug under `proyectos/`; defaults to the title slug. */
+    projectSlug?: string;
+    tags?: string[];
+}
+interface WriteNoteResult {
+    notePath: string;
+}
+/** Subfolder inside the vault where chamba writes its summaries. */
+declare const VAULT_NOTES_DIR = "proyectos";
+/**
+ * Write a structured summary note into an Obsidian vault at
+ * `<vault>/proyectos/<date>-<slug>.md` with valid YAML frontmatter.
+ */
+declare class VaultWriter {
+    private readonly fs;
+    private readonly clock;
+    constructor(fs: FilesystemPort, clock: ClockPort);
+    write(input: WriteNoteInput): Promise<WriteNoteResult>;
+}
+
+/** Relative path (from workspace root) of the chamba workspace file. */
+declare const WORKSPACE_DIR = ".chamba";
+declare const WORKSPACE_FILE = "workspace.md";
+declare const WORKSPACE_RELATIVE_PATH = ".chamba/workspace.md";
+interface ProjectRef {
+    name: string;
+    /** Path relative to the workspace root; `.` for the root project. */
+    path: string;
+    language?: string;
+    framework?: string;
+}
+interface Workspace {
+    root: string;
+    description: string;
+    languages: string[];
+    framework?: string;
+    conventions: string[];
+    projects: ProjectRef[];
+    /** Top-level directory names (without trailing slash), sorted. */
+    folderMap: string[];
+}
+/**
+ * Render a `Workspace` to the markdown that gets written to
+ * `.chamba/workspace.md`. Deterministic on purpose — no timestamps — so that
+ * `workspace_reload` produces meaningful diffs instead of churn.
+ */
+declare function renderWorkspaceMarkdown(ws: Workspace): string;
+
+type IssueSeverity = 'error' | 'warning';
+interface Issue {
+    code: string;
+    severity: IssueSeverity;
+    message: string;
+}
+interface ValidatePlanInput {
+    plan: string;
+    task: string;
+    context?: string;
+    workspace?: Workspace;
+}
+interface ValidationResult {
+    issues: Issue[];
+    suggestions: string[];
+    riskFlags: string[];
+}
+/**
+ * Validate a plan with programmatic heuristics — NO LLM. The editor's model
+ * already reasons; chamba only checks the plan's structure for known anti-patterns.
+ */
+declare function validatePlan(input: ValidatePlanInput): ValidationResult;
+
+interface PlanReview {
+    approved: boolean;
+    issues: Issue[];
+    suggestions: string[];
+    riskFlags: string[];
+}
+interface ReviewInput {
+    plan: string;
+    task: string;
+    context?: string;
+    workspace?: Workspace;
+}
+/**
+ * Heuristic plan reviewer. Runs `validatePlan` and approves only when there are
+ * no error-severity issues. Warnings and risk flags are surfaced but don't block.
+ * NO LLM — the editor's model decides what to do with the review.
+ */
+declare class Reviewer {
+    review(input: ReviewInput): PlanReview;
+}
+
+type WorkerKind = 'implementer' | 'tester' | 'reviewer';
+interface SubtaskSpec {
+    title: string;
+    worker: WorkerKind;
+    description: string;
+    filesLikelyTouched: string[];
+}
+interface GeneratePlanInput {
+    task: string;
+    context?: string;
+    workspace?: Workspace;
+}
+/** Default subtask scaffold every plan starts from. The model refines these. */
+declare function suggestSubtasks(): SubtaskSpec[];
+/** Seed "files likely touched" from the workspace map (top-level dirs/projects). */
+declare function suggestFilesLikelyTouched(workspace?: Workspace): string[];
+/**
+ * Produce a structured plan *template* (not a finished plan). The editor's model
+ * fills the placeholders. chamba never writes the actual plan — it only provides
+ * the skeleton and, later, reviews it. No LLM involved.
+ */
+declare function generatePlanTemplate(input: GeneratePlanInput): string;
+
+interface ProcessResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface ProcessExecOptions {
+    cwd?: string;
+}
+/**
+ * Run external processes behind a port so `@chamba/core` never imports
+ * `node:child_process`. Used from Phase 5 onward for git worktrees.
+ */
+interface ProcessPort {
+    exec(command: string, args: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
+}
+
+interface RecordedCall {
+    command: string;
+    args: string[];
+    cwd?: string;
+}
+type ProcessHandler = (command: string, args: string[]) => Partial<ProcessResult>;
+/**
+ * In-memory `ProcessPort` for tests. Records every call and returns whatever the
+ * handler produces (defaults to exit 0, empty output).
+ */
+declare class FakeProcess implements ProcessPort {
+    private readonly handler;
+    readonly calls: RecordedCall[];
+    constructor(handler?: ProcessHandler);
+    exec(command: string, args: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
+}
+
+/**
+ * In-memory `FilesystemPort` for tests (CLAUDE.md: tests de IO usan FilesystemPort
+ * en memoria). Paths are posix-style. Construct with a map of `path -> contents`.
+ */
+declare class MemoryFilesystem implements FilesystemPort {
+    private readonly files;
+    private readonly dirs;
+    constructor(initial?: Record<string, string>);
+    private norm;
+    private set;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    readDir(path: string): Promise<DirEntry[]>;
+}
+
+/**
+ * Minimal posix-style path helpers. `@chamba/core` avoids `node:path` so it can
+ * run in non-Node runtimes; all internal paths use `/` as separator.
+ */
+declare function joinPath(...parts: string[]): string;
+declare function basename(path: string): string;
+declare function dirname(path: string): string;
+/** Extension including the dot (e.g. `.ts`), or `''` if none. */
+declare function extname(path: string): string;
+
+interface RelevantNote {
+    path: string;
+    /** Number of keyword hits that made this note relevant. */
+    score: number;
+    /** First line that matched a keyword, trimmed. */
+    snippet: string;
+}
+interface ContextBuildInput {
+    workspace: Workspace;
+    task: string;
+    /** When set, search this Obsidian vault for notes relevant to the task. */
+    vaultPath?: string;
+    /** Soft cap on the produced context, in estimated tokens (~4 chars/token). */
+    maxTokens?: number;
+}
+interface BuiltContext {
+    context: string;
+    relevantNotes: string[];
+}
+/**
+ * Build the context block injected into the editor model's reasoning: a summary
+ * of the workspace plus, when a vault is present, the notes most relevant to the
+ * task (simple keyword search — semantic search is V2).
+ */
+declare class ContextBuilder {
+    private readonly fs;
+    constructor(fs: FilesystemPort);
+    build(input: ContextBuildInput): Promise<BuiltContext>;
+    private workspaceSection;
+    private notesSection;
+    private searchNotes;
+    private collectMarkdown;
+    private tryRead;
+}
+
+/**
+ * Line-based diff (LCS) producing a readable unified-ish output:
+ *   `  ` unchanged, `- ` removed, `+ ` added.
+ *
+ * Used by `workspace_reload` to show the model what a re-scan would change,
+ * without ever overwriting the user's hand-edited `workspace.md`.
+ */
+declare function diffLines(oldText: string, newText: string): string;
+/** True when the two texts are identical line-for-line. */
+declare function textsEqual(oldText: string, newText: string): boolean;
+
+interface VaultDetection {
+    found: boolean;
+    path?: string;
+    noteCount?: number;
+}
+interface DetectOptions {
+    /** Explicit vault path (e.g. from CHAMBA_OBSIDIAN_VAULT_PATH). Authoritative. */
+    explicitPath?: string;
+    /** Directories to probe for a `.obsidian/` marker when no explicit path. */
+    searchRoots?: string[];
+}
+/**
+ * Detect an Obsidian vault. An explicit path wins (the user set it on purpose);
+ * otherwise probe common roots for a `.obsidian/` directory. `@chamba/core` has
+ * no `os`/`fs`, so candidate roots are passed in by the caller.
+ */
+declare class ObsidianDetector {
+    private readonly fs;
+    constructor(fs: FilesystemPort);
+    detect(opts: DetectOptions): Promise<VaultDetection>;
+    private countNotes;
+}
+
+declare class WorkspaceScanner {
+    private readonly fs;
+    constructor(fs: FilesystemPort);
+    scan(root: string): Promise<Workspace>;
+    private loadIgnoreRules;
+    private walk;
+    private detectLanguages;
+    private detectProjects;
+    private readProject;
+    private detectConventions;
+    private detectDescription;
+    private findReadme;
+    private tryRead;
+}
+
+interface BranchNameInput {
+    /** `YYYY-MM-DD`. */
+    date: string;
+    taskSlug: string;
+    workerId: string;
+}
+/**
+ * Sanitize a value into a single git-ref-safe path component: lowercase, no
+ * spaces, no characters git forbids in refs (`~^:?*[\` etc.), no leading/trailing
+ * dots or dashes.
+ */
+declare function slugifyForGit(value: string): string;
+/** Branch convention: `chamba/<date>-<task-slug>/<worker-id>`. */
+declare function buildBranchName(input: BranchNameInput): string;
+/** Worktree directory relative to the repo root. */
+declare function worktreeRelativePath(taskSlug: string, workerId: string): string;
+
+/**
+ * Detect whether a directory is inside a git work tree, via
+ * `git rev-parse --is-inside-work-tree`. Caches per root for the session.
+ */
+declare class GitDetector {
+    private readonly process;
+    private readonly cache;
+    constructor(process: ProcessPort);
+    isGitRepo(root: string): Promise<boolean>;
+}
+
+declare class WorktreeError extends Error {
+    readonly name = "WorktreeError";
+}
+interface WorktreeHandle {
+    branch: string;
+    path: string;
+    taskSlug: string;
+    workerId: string;
+}
+interface CreateWorktreeInput {
+    root: string;
+    taskSlug: string;
+    workerId: string;
+    /** `YYYY-MM-DD` for the branch name. */
+    date: string;
+    baseBranch?: string;
+}
+interface ListedWorktree {
+    path: string;
+    head?: string;
+    branch?: string;
+}
+interface CleanupResult {
+    removed: boolean;
+    branchKept: boolean;
+    mergeSuggestion: string;
+}
+/**
+ * Manage git worktrees for isolated parallel work.
+ *
+ * Safety guarantees (see CLAUDE.md gotchas):
+ * - `cleanup` removes the worktree directory but NEVER deletes the branch and
+ *   NEVER merges. The branch stays for the human to review and merge by hand.
+ * - `git worktree remove` is run WITHOUT `--force`, so a dirty worktree fails
+ *   loudly instead of silently discarding work.
+ */
+declare class WorktreeManager {
+    private readonly process;
+    constructor(process: ProcessPort);
+    create(input: CreateWorktreeInput): Promise<WorktreeHandle>;
+    list(root: string): Promise<ListedWorktree[]>;
+    cleanup(root: string, branch: string): Promise<CleanupResult>;
+}
+
+export { type BranchNameInput, type BuiltContext, type CleanupResult, type ClockPort, type ContextBuildInput, ContextBuilder, type CreateWorktreeInput, type DetectOptions, type DirEntry, FakeProcess, FilesystemMemoryStore, type FilesystemPort, type GeneratePlanInput, GitDetector, type Issue, type IssueSeverity, type ListedWorktree, MEMORY_DIR, type Memory, MemoryFilesystem, type MemoryStore, type NoteFields, ObsidianDetector, type PlanReview, type ProcessExecOptions, type ProcessHandler, type ProcessPort, type ProcessResult, type ProjectRef, type RecordedCall, type RelevantNote, type RememberInput, type ReviewInput, Reviewer, type SubtaskSpec, VAULT_NOTES_DIR, type ValidatePlanInput, type ValidationResult, type VaultDetection, VaultWriter, WORKSPACE_DIR, WORKSPACE_FILE, WORKSPACE_RELATIVE_PATH, type WorkerKind, type Workspace, WorkspaceScanner, WorktreeError, type WorktreeHandle, WorktreeManager, type WriteNoteInput, type WriteNoteResult, basename, buildBranchName, diffLines, dirname, extname, generatePlanTemplate, joinPath, renderNote, renderWorkspaceMarkdown, slugify, slugifyForGit, suggestFilesLikelyTouched, suggestSubtasks, textsEqual, validatePlan, worktreeRelativePath };