@marwansaab/obsidian-vault-bootstrap 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing
+
+## Commit-message convention
+
+Every commit in this project follows the convention below. It is a superset
+of [Conventional Commits](https://www.conventionalcommits.org/) — the
+`type(scope): description` subject is the same; the body conventions
+layered on top are project-specific.
+
+### Subject line (≤72 chars, no trailing period)
+
+```
+<type>(<scope>): <description>
+```
+
+- **`type`** — one of: `feat`, `fix`, `chore`, `docs`, `ci`, `refactor`,
+  `test`, `perf`.
+- **`scope`** — the spec/feature ID when one exists (e.g. `013`,
+  `specs/009`); otherwise a component name (e.g. `git-extension`,
+  `release`, `readme`, `ci`).
+- **`description`** — lowercase, imperative present tense ("add",
+  "implement", "bump", "clarify", "remediate", "pivot to", "mark",
+  "scaffold", "revert", "enable"). Sentence fragment, no period. May end
+  with a parenthetical clarifier like `(round 4)`,
+  `(consistency + coverage)`, or a task-ID list like `(T001, T003, T006)`.
+
+Examples:
+
+- `feat(013): implement find_and_replace MCP tool with three-layer composition`
+- `docs(013): clarify enumeration and count semantics for find_and_replace (round 3)`
+- `chore(release): bump to 0.5.0 — spec 008 list_tags`
+
+### Body (blank line after subject, wrap ~72 cols)
+
+Lead with the **WHY** and **WHAT**, not the HOW (the diff shows the how).
+
+1. One-paragraph summary of what this commit does and why it exists
+   (link to the user clarification, spike outcome, analyzer finding, or
+   upstream dependency that prompted it).
+2. Itemised detail using bullets. Group related items under a SHOUTY-CAPS
+   prefix when categorising — e.g. `LAYER 1 — …`,
+   `T002 spike outcome (YYYY-MM-DD): NEGATIVE.`, `MINOR bump:` /
+   `PATCH bump:`, `F1 (HIGH) — …` (analyzer finding ID + severity),
+   `I2 (MEDIUM) — …` (consistency-issue ID + severity).
+3. Reference identifiers wherever they apply, in their native form, no
+   decoration: `FR-NNN` (functional requirement), `SC-NNN` (success
+   criterion), `TNNN` (task ID, e.g. `T009a`), `RNN` (research item, e.g.
+   `R12`), `Q1` (clarification question), `file/path.ts:LINE` (when
+   pointing at code), `PR #NN`, `commit shortsha`. Don't gloss IDs as
+   "the requirement" — name them.
+4. Be honest about tradeoffs, deferrals, and negative outcomes. If a
+   spike failed, say "NEGATIVE" and explain. If something is gated on
+   another piece of work, name the gate. If a task is deferred, say so
+   explicitly.
+5. Close with quality-gate results when the commit changes code:
+   `Quality gates: lint clean, typecheck clean, build clean, 572/572
+   tests pass (was 422 baseline, +150 new, 0 regressions).` Include
+   coverage % when the project tracks a coverage floor.
+6. For semver bumps, state the bump category and the rationale in one
+   sentence: `MINOR bump: adds the X public tool. Backward compatible —
+   no existing tool surface changes.` `PATCH bump (0.5.0 → 0.5.1) is the
+   honest signal: this PR ships internal preparation but no user-visible
+   capability.`
+
+Bodies are **mandatory** for `feat`, spec, and analyzer-remediation
+commits. They are optional for tiny one-line `fix`/`chore` commits, but
+even those keep the `type(scope): subject` form.
+
+### Trailers (blank line before, one per line, no wrap)
+
+For AI-assisted commits, append:
+
+```
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+```
+
+Substitute the actual model name + version of the assistant session
+that drafted the message.
+
+### Tone
+
+Direct, technical, no marketing language, no emoji. Prefer concrete
+nouns ("the dispatcher's `getRestService` throw path") over abstractions
+("the error handling"). Be willing to write things like "the templated
+commit messages are too generic to be useful" when reverting something.
+Write so a maintainer reading `git log` six months later can reconstruct
+the WHY without opening the PR.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marwan Saab
+
+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,75 @@
+# @marwansaab/obsidian-vault-bootstrap
+
+Initialise a complete Obsidian vault — folder structure, templates, MOCs,
+frontmatter conventions — and generate matching agent-instruction files for
+Claude, Cursor, Cline, or any AI coding assistant. Q&A-driven, npm-versioned,
+single source across your portfolio.
+
+> **Governance.** Every change in this repository is measured against the
+> project constitution:
+> [`.specify/memory/constitution.md`](.specify/memory/constitution.md) (v1.0.0,
+> ratified 2026-05-18). Principles I–VII are non-negotiable; reviewers cite
+> them by Roman numeral when accepting or rejecting changes.
+
+## Quickstart
+
+```bash
+git clone https://github.com/marwansaab/obsidian-vault-bootstrap.git
+cd obsidian-vault-bootstrap
+nvm use 22                  # or fnm / volta — Node >= 22.13.0 is required
+npm ci                      # honours the lockfile and .npmrc engine-strict
+npm run build
+npx . --help
+```
+
+v0.1 ships a placeholder CLI only — `npx . --help` and `npx . --version` are
+the entire end-user surface. See **Limitations (v0.1)** below for what does
+not work yet.
+
+## Quality gates
+
+The same six gates run locally and in CI (single source of truth per FR-014).
+Each gate exits non-zero on any failure and names the offending file in its
+output (FR-006).
+
+| Gate         | Command                 | Strictness bar                                 |
+| ------------ | ----------------------- | ---------------------------------------------- |
+| format-check | `npm run format:check`  | `prettier --check .` — zero divergence         |
+| lint         | `npm run lint`          | `eslint . --max-warnings 0`                    |
+| typecheck    | `npm run typecheck`     | `tsc --noEmit` — zero diagnostics, strict mode |
+| build        | `npm run build`         | `tsc` — zero warning-severity emit             |
+| test         | `npm test`              | `vitest run` — non-zero on any failure         |
+| coverage     | `npm run test:coverage` | statements ≥ 80% (vitest threshold)            |
+
+`npm run format` is the local fix-it command (writes prettier-formatted files
+back); it is **not** a CI gate.
+
+## Limitations (v0.1)
+
+v0.1 is a scaffold. The following are deliberately deferred — each will land
+with the spec that first consumes it. The full version history is in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+- No content-rendering pipeline yet — `core/`, `families/`, `templates/`, and
+  `projects/` ship empty (with `.gitkeep` placeholders) and will be populated
+  by subsequent specs.
+- No end-user subcommands beyond `--help` / `--version` — no `init`, no
+  `bootstrap`, no profile-driven render.
+- No interactive Q&A flow.
+- No content-bearing fixtures (instruction-content files, template files,
+  project-profile files arrive in later specs).
+- Not published to the public npm registry.
+- No Obsidian vault-folder initialisation pipeline.
+- **Single supported OS in CI: `ubuntu-latest`.** The package itself is Node
+  and runs anywhere Node does; the gate-verified OS in CI is Linux only.
+  Windows and macOS contributors can use the package, but their environment
+  is not covered by the CI matrix.
+- No code-graph integration.
+
+## Attributions
+
+v0.1 ships no upstream-derived code; every source file in this commit carries
+an `// Original — no upstream. <intent>.` header per constitution Principle
+VII. This section exists as a stable insertion point — future modules
+adapted from external projects will be listed here with their SPDX
+identifier and pinned commit hash.

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export interface CliResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export declare function main(argv: readonly string[]): CliResult;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAOA,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAuBD,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAwBvD"}

package/dist/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Original — no upstream. Placeholder CLI entry-point for the v1 scaffold.
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const HELP_TEXT = `obsidian-vault-bootstrap
+
+Usage:
+  npx . [--help|--version]
+
+Options:
+  -h, --help     Show this help text and exit.
+  -v, --version  Print the package version and exit.
+
+v0.1 ships a placeholder CLI only. See README.md for the v0.1 limitations
+and .specify/memory/constitution.md for the governance constitution.
+`;
+function readPackageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = resolve(here, "..", "package.json");
+    const raw = readFileSync(pkgPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.version;
+}
+export function main(argv) {
+    try {
+        const { values } = parseArgs({
+            args: [...argv],
+            options: {
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        if (values.version) {
+            return { exitCode: 0, stdout: `${readPackageVersion()}\n`, stderr: "" };
+        }
+        return { exitCode: 0, stdout: HELP_TEXT, stderr: "" };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `${message}\nUse --help for usage information.\n`,
+        };
+    }
+}
+function invokedDirectly() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === resolve(entry);
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    const result = main(process.argv.slice(2));
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    process.exit(result.exitCode);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,2EAA2E;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQ7C,MAAM,SAAS,GAAG;;;;;;;;;;;CAWjB,CAAC;AAEF,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAC;IACtD,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAuB;IAC1C,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;YAC3B,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;YACf,OAAO,EAAE;gBACP,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;gBACrC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;aACzC;YACD,MAAM,EAAE,IAAI;YACZ,gBAAgB,EAAE,KAAK;SACxB,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QAC1E,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACxD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO;YACL,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,EAAE;YACV,MAAM,EAAE,GAAG,OAAO,uCAAuC;SAC1D,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,eAAe;IACtB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,eAAe,EAAE,EAAE,CAAC;IACtB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvD,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@marwansaab/obsidian-vault-bootstrap",
+  "version": "0.1.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "bin": {
+    "obsidian-vault-bootstrap": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md"
+  ],
+  "scripts": {
+    "format:check": "prettier --check .",
+    "format": "prettier --write .",
+    "lint": "eslint . --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.2.4"
+  }
+}