Merge pull request #50 from frantic1048/dev/blend-create-add

feat!(blend): add order create and add commands

Author: houki-san[bot]

AGENTS.md

@@ -4,7 +4,8 @@
 
 Vanilla is the owner's dotfiles repository. Configs are defined as Nickel
 orders under `orders/` and deployed by the local `blend` CLI, a Rust tool in
-`blend/`. The root `bin/blend` entry is a symlink to the release build at
+`blend/`. The root `bin` entry is a symlink to `orders/bin/bin`, and
+`bin/blend` resolves through that Source directory to the release build at
 `target/release/blend`.
 
 This repo mixes two surfaces:
@@ -18,7 +19,7 @@ Keep those surfaces distinct when changing, testing, and interpreting CI.
 
 - `blend/` - Rust crate for the `blend` CLI.
 - `orders/` - active Nickel order definitions and config source files.
-- `bin/` - personal scripts deployed to `$PATH`, plus the `bin/blend` symlink.
+- `bin` - symlink to the physical personal-script Source at `orders/bin/bin`.
 - `legacy/` - stow-era or out-of-scope files kept for reference only; not
   managed by blend.
 - `screenshots/` - README screenshots.
@@ -86,7 +87,7 @@ Toolchain and dependency facts:
 Common tasks:
 
 ```sh
-just build       # release build + update bin/blend symlink
+just build       # release build + update the bin/blend entrypoint symlink
 just check       # bin/blend check
 just test        # cargo test --release in blend/
 just fmt-check   # cargo fmt --check in blend/
@@ -112,6 +113,10 @@ Inspect commands:
 Maintain commands:
 
 - `check [orders...]` - `[read]` validate Source order definitions.
+- `create <order>` - `[source]` scaffold a new empty Source order.
+- `add <order> <target>` - `[source]` import an absolute or `~`-prefixed
+  Target file/directory into an existing Source order. Useful flags:
+  `--prefix`, `--symlink follow|preserve`, `--allow-overlap`.
 - `format [orders...]` / `fmt` - `[source]` format Source order files; use
   `--check` in CI or review validation.
 - `init --upgrade` - `[source, target]` initialize or refresh
@@ -129,6 +134,13 @@ Global flags:
 - `--blend-dir` overrides the Blend Source root.
 - `--sandbox force|prefer|never` controls the process sandbox policy.
 
+Order Source paths:
+
+- `from_file` and `local` are relative to their order directory and must not be
+  absolute or normalize outside that directory.
+- File entries need an effective Target prefix from either `blend.prefix` or
+  entry-level `prefix`.
+
 ## Source Map
 
 For blend code changes, start here:

ERGO.md

@@ -2,11 +2,12 @@
 
 ## Context
 
-Investigating the current blend implementation (at `~/Vanilla/blend/`) to map essential user journeys and identify friction points. blend is a Rust-based dotfiles manager using Nickel DSL, managing ~55 orders across macOS and Linux.
+Investigating the current blend implementation (at `~/Vanilla/blend/`) to map essential user journeys and identify friction points. blend is a Rust-based dotfiles manager using Nickel DSL, managing roughly 50 orders across macOS and Linux.
 
-**Current CLI commands:** default status, `sync` (alias `s`), `view`, `table`,
-and `init`. The previous `ship`, `sample`, and task/upgrade CLI paths have been
-removed or moved to the top-level `justfile`.
+**Current CLI commands:** default status, `status`, `view`, `table`, `check`,
+`create`, `add`, `format` (alias `fmt`), `init`, and `sync` (alias `s`). The
+previous `ship`, `sample`, and task/upgrade CLI paths have been removed or
+moved to the top-level `justfile`.
 
 ---
 
@@ -50,10 +51,11 @@ removed or moved to the top-level `justfile`.
 ### Current Flow
 
 ```
-1. Create dir:           mkdir orders/my-app
-2. Write order.ncl:      (manually, from memory or by copying another order)
-3. For plaintext:        cp ~/.config/my-app/config orders/my-app/config
-4. For structured:       Manually transcribe TOML/JSON/YAML into Nickel from_config syntax
+1. Scaffold order:       blend create my-app
+2. Import plaintext:     blend add my-app ~/.config/my-app/config
+   2a. Or explicit root: blend add my-app --prefix ~/.config/my-app ~/.config/my-app/config
+3. For structured:       Manually transcribe TOML/JSON/YAML into Nickel from_config syntax
+4. Validate:             blend check my-app
 5. Preview:              blend view my-app
 6. Deploy:               blend sync my-app
 ```
@@ -62,19 +64,18 @@ removed or moved to the top-level `justfile`.
 
 | # | Issue | Severity | Detail |
 |---|-------|----------|--------|
-| 1 | **No scaffolding command** | High | No `blend add my-app` to create order skeleton with boilerplate order.ncl |
+| 1 | **~~No scaffolding command~~** | ~~High~~ | **Resolved** — `blend create <order>` scaffolds the Source order and `blend add <order> <target>` imports existing Target files/directories |
 | 2 | **Manual config transcription for structured** | High | User must hand-convert a TOML/JSON file into Nickel `from_config = { ... }` syntax. For a 200-line starship.toml, this is painful and error-prone |
 | 3 | **Must know Nickel syntax** | Medium | No inline documentation, no `blend help new-order` with examples |
-| 4 | **No first-class validation command** | Low | `just check` wraps `bin/blend view --dry-run`, but there is no dedicated `blend check`/`blend lint` CLI yet |
+| 4 | **~~No first-class validation command~~** | ~~Low~~ | **Resolved** — `blend check [orders...]` validates Source order definitions without deploying |
 | 5 | **Schema contract usage is implicit** | Low | User should pipe to `| Order` at end of order.ncl for editor/Nickel validation, but the workflow does not strongly suggest it; Rust deserialization still validates the evaluated shape |
 
 ### Improvement Ideas
 
-- `blend add <name> [--from <path>]` command that:
-  - Creates `orders/<name>/order.ncl` with sensible defaults
-  - If `--from ~/.config/app/config.toml` is given: auto-detects format, parses the file, generates `from_config` Nickel syntax using `json_to_nickel()` (already implemented in `ast_utils.rs`)
-  - For directories: creates `from_file` entry pointing to copied dir
-- `blend check`: validate all order.ncl files without deploying (first-class CLI wrapper around fast Nickel eval + schema check)
+- ~~Order scaffolding/import~~: **Implemented** via `blend create <order>` and
+  `blend add <order> <target>` for `from_file` entries.
+- Structured import remains future work: auto-detect a TOML/JSON/YAML Target,
+  parse it, and generate `from_config` Nickel syntax using `json_to_nickel()`.
 
 ---
 
@@ -158,14 +159,14 @@ These friction points from the original analysis have been addressed by `blend s
 
 | # | Issue | Severity | Detail |
 |---|-------|----------|--------|
-| 1 | **No first-class validation-only command** | Medium | No `blend check` or `blend lint` CLI yet; the top-level `just check` currently uses `bin/blend view --dry-run` |
+| 1 | **~~No first-class validation-only command~~** | ~~Medium~~ | **Resolved** — `blend check [orders...]` validates Source order definitions without deploying |
 | 2 | **No rollback** | Medium | If a force deploy overwrites a config and breaks an app, there's no `blend rollback` or automatic backup |
 | 3 | **Nickel errors can be opaque** | Low | Nickel evaluation errors include source info but can be hard to trace for contract violations |
 | 4 | **No pre-sync backup** | Low | Sync overwrites in-place. A backup of the previous deployed version would help recovery |
 
 ### Improvement Ideas
 
-- `blend check`: validate all orders without building (fast Nickel eval + schema check)
+- ~~`blend check`~~: **Implemented** — validate all orders without deploying (fast Nickel eval + schema check)
 - Auto-backup before Source -> Target sync: copy previous Target file to `~/.cache/blend/backups/<order>/<file>.bak`
 - `blend rollback <order>`: restore from backup
 
@@ -176,10 +177,12 @@ These friction points from the original analysis have been addressed by `blend s
 ### Quick Wins (low effort, high impact)
 1. ~~**Fix bootstrap script**: install proto/Rust, build `bin/blend`, then deploy via `just bootstrap`~~
 2. **First-run message**: When all orders are pending, show "Run `blend sync` to review and deploy"
-3. **`blend check` command**: Validate all order.ncl files without deploying
+3. ~~**`blend check` command**~~: **Implemented** — validate all order.ncl files without deploying
 
 ### Medium Effort
-4. **`blend add <name> [--from <path>]`**: Scaffold new orders with auto-import from existing deployed configs (can reuse existing `json_to_nickel()` for format conversion). This covers the "capture existing config into a new order" use case — currently there's no way to pull a config from the filesystem into a new order without manual setup.
+4. ~~**`blend create` / `blend add` for `from_file` import**~~:
+   **Implemented** — remaining work is structured `from_config` import from
+   existing TOML/JSON/YAML Targets.
 5. **`--no-rewrite` info display**: Show branch context and Nickel snippets for manual merge
 6. **Suggest ignore patterns**: Auto-detect frequently changing fields
 
@@ -195,6 +198,9 @@ These friction points from the original analysis have been addressed by `blend s
 Features that were in "Improvement Ideas" and are now implemented:
 
 - **`blend sync`** — bidirectional sync with interactive Source/Target/skip choices (Journey 3, items 1/3/4)
+- **`blend check`** — validation-only Source order checks
+- **`blend create`** — scaffold an empty Source order
+- **`blend add`** — import existing Target files/directories as `from_file` entries
 - **`blend sync --force-source-to-target`** — non-interactive Source -> Target all
 - **`blend sync --force-target-to-source`** — non-interactive Target -> Source all
 - **Surgical .ncl rewrite** — auto-patches Nickel source for data-only and conditional values

NEW_BLEND.md

@@ -35,7 +35,7 @@ Two config modes per file entry:
 | Mode | Source | Rendering | Sync-back |
 |------|--------|-----------|-----------|
 | `from_config` | Inline Nickel data/expressions | Evaluated → rendered to target format | Context-aware AST rewrite |
-| `from_file` | Files/dirs in `orders/<order>/` | Copied as-is | File copy back |
+| `from_file` | Relative files/dirs inside `orders/<order>/` | Copied as-is | File copy back |
 
 ---
 
@@ -60,14 +60,14 @@ Each order is defined by `orders/<order>/order.ncl`. The evaluated result must c
 |-------|------|----------|-------------|
 | `name` | String | Yes (for `from_config`) | Destination filename. Combined with prefix for target path. Auto-set from `from_file` if omitted. |
 | `from_config` | Record/Array | One of these | Inline structured config data, evaluated by Nickel and rendered to target format |
-| `from_file` | String | One of these | Path to file/directory in the order dir, copied as-is |
-| `prefix` | Array<String> | No | Per-file prefix override (default: inherits global `blend.prefix`) |
+| `from_file` | String | One of these | Relative path to file/directory in the order dir, copied as-is. Absolute paths and paths that normalize outside the order dir are rejected. |
+| `prefix` | Array<String> | No | Per-file prefix override (default: inherits global `blend.prefix`). File entries require an effective prefix from either place. |
 | `format` | String | No | Output format override (default: inferred from `name` extension) |
 | `ignore` | Array<String> | No | Keys/patterns to exclude from diff (merged with global) |
 | `when` | Record | No | Per-file condition: `{ os, arch, hostname }` |
 | `symlink` | Bool | No | Create symlink instead of copying (`from_file` only) |
 | `exclude` | Array<String> | No | Glob patterns to skip in `from_file` directories |
-| `local` | String | No | Local overlay directory for machine-specific overrides (auto-created, gitignored) |
+| `local` | String | No | Relative local overlay directory for machine-specific overrides (auto-created, gitignored). It follows the same non-escaping Source path rule as `from_file`. |
 | `immutable` | Bool | No | Set OS immutable flag after deploying (macOS `chflags uchg`, Linux `chattr +i`) |
 
 ### Example: structured config (from_config)
@@ -325,7 +325,7 @@ Prompt diffs use explicit side markers instead of traditional `+/-`:
 
 ```
 blend                              Status: show all orders and sync state
-blend sync [orders...]             Interactive bidirectional sync (default)
+blend sync [orders...]             Interactive bidirectional sync
 blend s [orders...]                Alias for `blend sync`
 blend sync --force-source-to-target
                                    Force-apply Source values to Targets
@@ -337,6 +337,10 @@ blend view -c [orders...]          Show generated content only (no diff)
 blend view -a [orders...]          Show both content and diff
 blend view -s [orders...]          Short mode: omit up-to-date entries
 blend check [orders...]            Typecheck/evaluate order.ncl files
+blend create <order>               Scaffold an empty Source order
+blend add <order> <target>         Import a Target file/directory into an order
+blend add <order> --prefix <path> <target>
+                                   Strip an explicit Target prefix before import
 blend format [orders...]           Format order.ncl files
 blend format --check [orders...]   Check order.ncl formatting without writing
 blend table                        Output order info as HTML table (for README)
@@ -453,7 +457,7 @@ In `.ncl` files, use `\u{xxxx}` escape sequences for non-ASCII characters (e.g.,
 - **Three-way merge context**: Snapshot-backed prompts are implemented for conflict explanation. This is not a full automatic merge engine, but `blend` can now show Source/Target/Base context when a snapshot exists.
 - **Secrets management**: Deferred to v2. Focus on core config management first.
 - **JSONC round-trip**: Output JSON without comments. Comments live in Nickel source.
-- **Schema validation**: Orders are validated through the Nickel `| Order` contract when present, then through Rust deserialization and `resolve_defaults()`. Generated `order.contract.ncl` and `metadata.ncl` freshness is checked for read-only commands and repaired by `init`/`sync`.
+- **Schema validation**: Orders are validated through the Nickel `| Order` contract when present, then through Rust deserialization, `resolve_defaults()`, and Source path checks. Generated `order.contract.ncl` and `metadata.ncl` freshness is checked for read-only commands and repaired by `init`/`sync`.
 
 ---
 

blend/README.md

@@ -28,9 +28,14 @@ src/
 ├── metadata.rs          OS/arch/hostname/desktop/user detection
 ├── output.rs            log helpers (info/warn/error/success)
 │
-├── commands.rs          re-exports cmd_sync / cmd_view / cmd_status / cmd_table
+├── commands.rs          re-exports command handlers
 ├── commands/
+│   ├── add.rs           import Target files/directories into Source orders
+│   ├── create.rs        scaffold empty Source orders
+│   ├── check.rs         validate Source order definitions
+│   ├── format.rs        format order.ncl files
 │   ├── helpers.rs       shared symlink + diff-aggregation helpers
+│   ├── init.rs          refresh generated contract + metadata files
 │   ├── sync.rs          bidirectional sync + per-key interactive flow
 │   ├── view.rs          render preview & diff
 │   ├── status.rs        order state table (parallel via rayon)
@@ -60,7 +65,7 @@ src/
     └── text.rs          line-based diffing for plaintext
 
 tests/
-├── sync_e2e.rs          end-to-end CLI tests (39 scenarios)
+├── sync_e2e.rs          end-to-end CLI tests
 └── fixtures/            .ncl + deployed-file fixtures
 ```
 

blend/src/cli.rs

@@ -1,4 +1,4 @@
-use clap::{Parser, Subcommand};
+use clap::{Parser, Subcommand, ValueEnum};
 use std::path::PathBuf;
 
 use crate::sandbox::SandboxMode;
@@ -23,6 +23,8 @@ Inspect:
 
 Maintain:
   check   [read] Validate Source order definitions
+  create  [source] Create a new order
+  add     [source] Add a Target file or directory to an order
   format  [source] Format Source order files
   init    [source, target] Initialize or refresh Blend metadata and config
   sync    [source, target] Reconcile Source orders and Target files
@@ -131,6 +133,37 @@ pub enum MaintainCommands {
         orders: Vec<String>,
     },
 
+    /// [source] Create a new order
+    Create {
+        /// Order to create
+        order: String,
+    },
+
+    /// [source] Add a Target file or directory to an existing order
+    #[command(long_about = "\
+[source] Add a Target file or directory to an existing order
+
+Copies the Target path into the order Source tree and appends a file entry to order.ncl.")]
+    Add {
+        /// Order to add the Target path to
+        order: String,
+
+        /// Target file or directory to add; must be absolute or start with ~
+        path: PathBuf,
+
+        /// Target prefix to strip before copying into the order Source tree
+        #[arg(long)]
+        prefix: Option<String>,
+
+        /// Symlink deployment policy; required when the Target path is a symlink
+        #[arg(long)]
+        symlink: Option<SymlinkMode>,
+
+        /// Allow overlapping Target paths with existing entries
+        #[arg(long)]
+        allow_overlap: bool,
+    },
+
     /// [source] Format Source order files
     #[command(alias = "fmt")]
     Format {
@@ -153,3 +186,11 @@ Writes or refreshes orders/order.contract.ncl and orders/metadata.ncl. For a new
         upgrade: bool,
     },
 }
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
+pub enum SymlinkMode {
+    /// Copy resolved Target content into Source and deploy a real file/directory
+    Follow,
+    /// Copy resolved Target content into Source and deploy the Target as a symlink
+    Preserve,
+}

blend/src/commands.rs

@@ -1,4 +1,6 @@
+pub mod add;
 pub mod check;
+pub mod create;
 pub mod format;
 pub mod helpers;
 pub mod init;
@@ -7,7 +9,9 @@ pub mod sync;
 pub mod table;
 pub mod view;
 
+pub use add::cmd_add;
 pub use check::cmd_check;
+pub use create::cmd_create;
 pub use format::cmd_format;
 pub use init::cmd_init;
 pub use status::cmd_status;