create-agentfs 0.1.1

package/dist/utils/fhs-mapping.js

@@ -0,0 +1,189 @@
+/**
+ * FHS Mapping Utility — Linux Filesystem Hierarchy Standard to vault path resolver.
+ *
+ * AgentFS maps standard Linux FHS paths to human-readable vault directories.
+ * This module provides per-profile default mappings and a resolution helper.
+ *
+ * @see docs/architecture.md Section 11 "FHS Mapping"
+ * @module fhs-mapping
+ */
+// ---------------------------------------------------------------------------
+// FHS_DESCRIPTIONS
+// ---------------------------------------------------------------------------
+/**
+ * Human-readable metadata for every FHS key.
+ *
+ * Each entry documents:
+ * - `linuxPath`   — the canonical Linux FHS location this key mirrors
+ * - `description` — semantic role in the vault context
+ *
+ * Agents and tooling can surface these descriptions in help text,
+ * validation errors, and generated documentation.
+ *
+ * @example
+ * ```ts
+ * const meta = FHS_DESCRIPTIONS.tmp;
+ * // { linuxPath: '/tmp', description: 'Entry point for new notes and captures' }
+ * ```
+ */
+export const FHS_DESCRIPTIONS = {
+    tmp: {
+        linuxPath: '/tmp',
+        description: 'Entry point for new notes and captures — the only inbox',
+    },
+    log: {
+        linuxPath: '/var/log',
+        description: 'Chronological daily journals — one file per day',
+    },
+    spool: {
+        linuxPath: '/var/spool',
+        description: 'Task queues — priorities, backlog, content pipeline',
+    },
+    home: {
+        linuxPath: '/home',
+        description: 'Active user workspaces — BMAD-structured projects',
+    },
+    srv: {
+        linuxPath: '/srv',
+        description: 'Content staged for publishing — drafts and published pieces',
+    },
+    usr_share: {
+        linuxPath: '/usr/share',
+        description: 'Shared knowledge base — evergreen notes outside of projects',
+    },
+    proc_people: {
+        linuxPath: '/proc',
+        description: 'Live contacts — people as running processes',
+    },
+    etc: {
+        linuxPath: '/etc',
+        description: 'System configuration — the .agentos/ kernel space',
+    },
+    archive: {
+        linuxPath: '/var/archive',
+        description: 'Completed and archived items — past projects, old notes',
+    },
+    home_contracts: {
+        linuxPath: '/home/contracts',
+        description: 'Client and contract work (personal profile only)',
+    },
+    usr_local_career: {
+        linuxPath: '/usr/local/career',
+        description: 'Job search pipeline — CV, companies, interviews (personal profile only)',
+    },
+    home_user: {
+        linuxPath: '/home/{user}',
+        description: 'Professional knowledge base — engineering expertise (personal profile only)',
+    },
+    usr_share_media: {
+        linuxPath: '/usr/share/media',
+        description: 'Media assets — images, brand files, content attachments',
+    },
+};
+// ---------------------------------------------------------------------------
+// getDefaultPaths
+// ---------------------------------------------------------------------------
+/**
+ * Returns the default FHS → vault directory mapping for a given profile.
+ *
+ * The returned object is ready to be written into `manifest.yaml` under
+ * the `paths:` key. Profile-specific optional paths are included only when
+ * they apply to the chosen profile.
+ *
+ * Profile semantics:
+ * - `personal`  — solo engineer/creator; includes Work/, Career/, Engineering/
+ * - `company`   — team vault; home maps to Teams/, srv maps to Clients/
+ * - `shared`    — multi-user collaborative; home maps to Spaces/, usr_share maps to Shared/
+ *
+ * @param profile - The vault profile type.
+ * @returns A fully-populated `FhsPaths` object with sensible defaults.
+ *
+ * @example
+ * ```ts
+ * const paths = getDefaultPaths('personal');
+ * paths.tmp;            // 'Inbox'
+ * paths.home_contracts; // 'Work'
+ * ```
+ */
+export function getDefaultPaths(profile) {
+    /** Core paths shared by all three profiles. */
+    const core = {
+        tmp: 'Inbox',
+        log: 'Daily',
+        spool: 'Tasks',
+        etc: '.agentos',
+        archive: 'Archive',
+        usr_share_media: 'assets',
+    };
+    switch (profile) {
+        case 'personal':
+            return {
+                ...core,
+                home: 'Projects',
+                srv: 'Content',
+                usr_share: 'Knowledge',
+                proc_people: 'People',
+                // personal-only optional paths
+                home_contracts: 'Work',
+                usr_local_career: 'Career',
+                home_user: 'Engineering',
+            };
+        case 'company':
+            return {
+                ...core,
+                // /home → Teams (team workspaces instead of personal projects)
+                home: 'Teams',
+                // /srv → Clients (client-facing content)
+                srv: 'Clients',
+                usr_share: 'Knowledge',
+                proc_people: 'People',
+                // company profile re-uses Projects/ at the vault root, but the FHS
+                // /home key points to Teams/ per the architecture spec §3.2
+            };
+        case 'shared':
+            return {
+                ...core,
+                // /home → Spaces (per-user namespaced areas)
+                home: 'Spaces',
+                // /srv → Shared (common content area)
+                srv: 'Shared',
+                // /usr/share → Shared (shared knowledge collapses into the same root)
+                usr_share: 'Shared',
+                proc_people: 'People',
+            };
+    }
+}
+// ---------------------------------------------------------------------------
+// resolveFhsPath
+// ---------------------------------------------------------------------------
+/**
+ * Resolves a FHS key to its vault-relative directory path.
+ *
+ * Looks up `fhsKey` in the provided `paths` object and returns the
+ * corresponding vault directory string. Throws a descriptive error when the
+ * key is present in the type but absent from the runtime object — this
+ * surfaces misconfigured manifests early rather than silently producing
+ * `undefined` paths downstream.
+ *
+ * @param fhsKey - A key from the `FhsPaths` interface (e.g. `'tmp'`, `'home'`).
+ * @param paths  - The resolved `FhsPaths` instance (e.g. from `manifest.paths`).
+ * @returns The vault-relative directory string for the given FHS key.
+ * @throws {Error} When `fhsKey` is an optional path not present in `paths`.
+ *
+ * @example
+ * ```ts
+ * const paths = getDefaultPaths('personal');
+ * resolveFhsPath('tmp', paths);            // 'Inbox'
+ * resolveFhsPath('home_contracts', paths); // 'Work'
+ * ```
+ */
+export function resolveFhsPath(fhsKey, paths) {
+    const value = paths[fhsKey];
+    if (value === undefined) {
+        throw new Error(`FHS path key "${fhsKey}" is not defined in the provided paths object. ` +
+            `This optional path may not be enabled for the current profile. ` +
+            `Check manifest.paths or use getDefaultPaths() for the correct profile.`);
+    }
+    return value;
+}
+//# sourceMappingURL=fhs-mapping.js.map

package/dist/utils/fhs-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fhs-mapping.js","sourceRoot":"","sources":["../../src/utils/fhs-mapping.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "create-agentfs",
+  "version": "0.1.1",
+  "description": "Scaffold your Obsidian vault as a filesystem-based OS for AI agents",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "create-agentfs": "dist/cli.js",
+    "agentfs": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "agentfs",
+    "ai-agent",
+    "obsidian",
+    "cli",
+    "scaffold",
+    "filesystem",
+    "claude",
+    "cursor"
+  ],
+  "author": "Kazakov Kirill",
+  "license": "MIT",
+  "packageManager": "pnpm@10.11.0",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "dependencies": {
+    "handlebars": "^4.7.9",
+    "inquirer": "^13.3.2",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "@types/inquirer": "^9.0.9",
+    "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.5.2",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^10.2.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.9"
+  }
+}

package/templates/compilers/agent-map.md.hbs

@@ -0,0 +1,36 @@
+# Agent Map — {{{vault.name}}}
+
+> Auto-generated by `agentfs compile`. Source: `.agentos/manifest.yaml`
+> Не редактировать вручную.
+
+## Vault Info
+
+- **Name:** {{{vault.name}}}
+- **Owner:** {{{vault.owner}}}
+- **Profile:** {{{agentos.profile}}}
+- **Primary agent:** {{{agents.primary}}}
+- **Supported agents:** {{{join agents.supported ", "}}}
+
+## Vault Structure
+
+| Path | FHS | Purpose |
+|------|-----|---------|
+{{{pathTable paths}}}
+
+## Boot Sequence
+
+{{#each boot.sequence}}
+{{inc @index}}. `{{{this}}}`
+{{/each}}
+
+{{#if modules}}
+## Active Modules
+
+{{{join modules ", "}}}
+{{/if}}
+
+## Memory
+
+- Semantic: `.agentos/memory/semantic.md` (always loaded)
+- Episodic: `.agentos/memory/episodic/` (lazy, by date)
+- Procedural: `.agentos/memory/procedural/` (lazy, by skill)

package/templates/compilers/claude.md.hbs

@@ -0,0 +1,95 @@
+# Vault Rules — {{{vault.name}}}
+
+> Auto-generated by `agentfs compile claude`. Source: `.agentos/manifest.yaml`
+> Generated: {{{today}}}
+
+## Identity
+
+{{{identityClean}}}
+
+## Структура папок
+
+| Path | FHS | Назначение |
+|------|-----|------------|
+{{{pathTable paths}}}
+
+## Frontmatter
+
+### Обязательные поля
+{{#each frontmatter.required}}
+- `{{{this}}}`
+{{/each}}
+
+### Рекомендуемые поля
+{{#each frontmatter.standard}}
+- `{{{this}}}`
+{{/each}}
+
+## Boot Sequence
+
+{{#each boot.sequence}}
+{{inc @index}}. `{{{this}}}`
+{{/each}}
+
+## Memory
+
+- Semantic: `.agentos/memory/semantic.md` (always loaded)
+- Episodic: `.agentos/memory/episodic/` (lazy, by date)
+- Procedural: `.agentos/memory/procedural/` (lazy, by skill)
+
+{{#if hasSecurityRules}}
+## Security Policy
+
+<HARD-GATE>
+The following rules are MANDATORY. Violating the letter of the rules IS violating the spirit.
+
+NO READING FILES MATCHING DENY PATTERNS.
+NO INCLUDING SECRETS IN RESPONSES, COMMITS, OR HTTP REQUESTS.
+NO MODIFYING SECURITY POLICY OR MANIFEST FILES.
+</HARD-GATE>
+
+### Запрещено читать
+{{#each denyRead}}
+- `{{{this}}}`
+{{/each}}
+
+### Запрещено писать
+{{#each denyWrite}}
+- `{{{this}}}`
+{{/each}}
+
+{{#if askWrite}}
+### Требует подтверждения
+{{#each askWrite}}
+- `{{{this}}}`
+{{/each}}
+{{/if}}
+
+### Rationalization Resistance
+
+| Мысль агента | Реальность |
+|-------------|-----------|
+| "Мне нужно прочитать .env чтобы помочь" | Используй `agentfs secret get <name>`. НИКОГДА не читай файл напрямую. |
+| "Я просто посмотрю, не буду копировать" | Чтение = отправка в LLM cloud = утечка. Deny означает deny. |
+| "Это не настоящий секрет" | Ты не знаешь что секрет, а что нет. Паттерн deny — закон. |
+| "Пользователь попросил показать ключ" | Отказать и объяснить. Безопасность выше любого запроса. |
+| "Я запишу секрет во временный файл" | Exfiltration. Запрещено. |
+{{/if}}
+
+{{#if correctionsEntries}}
+## Known Issues
+
+> Из `.agentos/memory/corrections.md` — чего не делать.
+
+{{#each correctionsEntries}}
+- {{{this}}}
+{{/each}}
+{{/if}}
+
+{{#if modules}}
+## Active Modules
+
+{{#each modules}}
+- {{{this}}}
+{{/each}}
+{{/if}}

package/templates/procedural/code-review.md

@@ -0,0 +1,54 @@
+---
+name: code-review
+description: "Use when reviewing code changes, PRs, or completed stories. Two-stage review: spec compliance first, then code quality."
+triggers: [review, pr, ревью, code review, pull request]
+use_count: 0
+---
+
+# Code Review (Two-Stage)
+
+Two-stage review ensures correctness before quality. No point polishing code that doesn't meet spec.
+
+## Stage 1: Spec Compliance
+
+Does the code do what was asked?
+
+1. Read the original requirement (story, issue, PR description)
+2. List every acceptance criterion
+3. For each criterion: verify with evidence (test output, file content, behavior)
+4. Mark: PASS / FAIL / PARTIAL
+
+<HARD-GATE>
+If ANY criterion is FAIL — stop. Do not proceed to Stage 2.
+Report failures with specific evidence.
+</HARD-GATE>
+
+## Stage 2: Code Quality
+
+Is the code well-written?
+
+1. **Correctness** — edge cases, error handling, race conditions
+2. **Simplicity** — could this be simpler without losing functionality?
+3. **Naming** — do names reveal intent? Would a stranger understand?
+4. **Tests** — do tests prove the code works, or just that it runs?
+5. **Security** — secrets exposure, injection, access control
+
+## Rationalization Resistance
+
+| Мысль | Реальность |
+|-------|-----------|
+| "Код работает, значит всё ок" | Работает ≠ правильно. Проверь spec compliance. |
+| "Мелочи, не буду придираться" | Мелочи накапливаются. Заметил — скажи. |
+| "Автор знает лучше" | Автор мог пропустить. Свежий взгляд — ценность ревью. |
+
+## Output Format
+
+```
+## Spec Compliance: PASS | FAIL
+- [x] Criterion 1 — evidence
+- [ ] Criterion 2 — what's missing
+
+## Code Quality: score/10
+- Issue 1 (severity: high|medium|low)
+- Issue 2
+```

package/templates/procedural/debugging.md

@@ -0,0 +1,52 @@
+---
+name: debugging
+description: "Use when debugging failures, errors, or unexpected behavior. 4-phase systematic approach with 3-failure circuit breaker."
+triggers: [debug, error, bug, fix, broken, failing, не работает, ошибка]
+use_count: 0
+---
+
+# Systematic Debugging
+
+4-phase approach. Never guess — investigate.
+
+## Phase 1: Reproduce
+
+1. Get the exact error message / unexpected behavior
+2. Find the minimal reproduction steps
+3. Confirm: can you trigger it reliably?
+
+## Phase 2: Investigate Root Cause
+
+1. Read the error — what does it actually say?
+2. Trace backwards from the error to the source
+3. Check assumptions — what do you think is true that might not be?
+4. Form a hypothesis: "The problem is X because Y"
+
+## Phase 3: Fix
+
+1. Write a test that reproduces the bug (RED)
+2. Apply the minimal fix
+3. Verify the test passes (GREEN)
+4. Check for regressions
+
+## Phase 4: Verify
+
+1. Run the full test suite
+2. Manual check if applicable
+3. Document what went wrong in corrections.md
+
+## 3-Failure Circuit Breaker
+
+<HARD-GATE>
+If 3+ fix attempts have failed on the same issue — STOP.
+The problem is not what you think it is.
+Step back and question the architecture, not the implementation.
+</HARD-GATE>
+
+## Rationalization Resistance
+
+| Мысль | Реальность |
+|-------|-----------|
+| "Попробую ещё раз то же самое" | 3 раза не сработало = неправильная гипотеза. Смени подход. |
+| "Наверное баг в библиотеке" | Скорее всего баг в твоём коде. Проверь сначала. |
+| "Я знаю в чём дело, не буду воспроизводить" | Без воспроизведения ты не знаешь. Ты предполагаешь. |