@lifestreamdynamics/vault-cli 1.4.4 → 1.4.6

package/README.md

@@ -158,7 +158,7 @@ lsvault auth login --api-key lsv_k_your_api_key_here
 
 **Create an API Key:**
 ```bash
-lsvault keys create --name "CI/CD Pipeline" --scopes vaults:read,documents:read
+lsvault keys create "CI/CD Pipeline" --scopes read,write
 ```
 
 ### Email/Password Authentication
@@ -313,46 +313,52 @@ lsvault search "meeting" --tags work,urgent --limit 10
 | Command | Description |
 |---------|-------------|
 | `lsvault teams list` | List all teams |
-| `lsvault teams create` | Create a new team |
+| `lsvault teams create <name>` | Create a new team |
 | `lsvault teams get <teamId>` | Get team details |
 | `lsvault teams update <teamId>` | Update team settings |
 | `lsvault teams delete <teamId>` | Delete a team |
-| `lsvault teams members <teamId>` | List team members |
-| `lsvault teams invite <teamId>` | Invite user to team |
-| `lsvault teams remove <teamId> <userId>` | Remove member from team |
+| `lsvault teams members list <teamId>` | List team members |
+| `lsvault teams members update <teamId> <userId> --role <role>` | Update a member's role (admin/editor/viewer) |
+| `lsvault teams members remove <teamId> <userId>` | Remove member from team |
+| `lsvault teams invitations create <teamId> <email> --role <role>` | Invite a user to the team |
+| `lsvault teams invitations list <teamId>` | List pending invitations |
+| `lsvault teams invitations revoke <teamId> <invitationId>` | Revoke an invitation |
+| `lsvault teams vaults list <teamId>` | List shared team vaults |
+| `lsvault teams vaults create <teamId> <name>` | Create a shared team vault |
 
 **Example:**
 ```bash
 # Create a team
-lsvault teams create --name "Engineering" --description "Dev team workspace"
+lsvault teams create "Engineering" --description "Dev team workspace"
 
 # Invite a member
-lsvault teams invite team_abc123 --email engineer@example.com --role member
+lsvault teams invitations create team_abc123 engineer@example.com --role editor
 
 # List members
-lsvault teams members team_abc123
+lsvault teams members list team_abc123
 ```
 
 ### Sharing & Publishing
 
 | Command | Description |
 |---------|-------------|
-| `lsvault shares list` | List all share links |
+| `lsvault shares list <vaultId> <path>` | List share links for a document |
 | `lsvault shares create <vaultId> <path>` | Create a share link for a document |
-| `lsvault shares revoke <shareId>` | Revoke a share link |
-| `lsvault publish list` | List published documents |
-| `lsvault publish create <vaultId> <path>` | Publish a document publicly |
-| `lsvault publish unpublish <publishId>` | Unpublish a document |
+| `lsvault shares revoke <vaultId> <shareId>` | Revoke a share link |
+| `lsvault publish list <vaultId>` | List published documents in a vault |
+| `lsvault publish create <vaultId> <path> --slug <slug>` | Publish a document publicly |
+| `lsvault publish delete <vaultId> <path>` | Unpublish a document |
 
 **Example:**
 ```bash
-# Create a password-protected share link
-lsvault shares create vault_abc123 /reports/Q1.md \
-  --password secret123 \
-  --expires-in 7d
+# Create a password-protected share link (prompts for the password)
+lsvault shares create vault_abc123 reports/Q1.md \
+  --permission view \
+  --protect-with-password \
+  --expires 2026-12-31
 
 # Publish a document
-lsvault publish create vault_abc123 /blog/post.md --slug my-first-post
+lsvault publish create vault_abc123 blog/post.md --slug my-first-post
 ```
 
 ### Publish Vault Commands
@@ -386,26 +392,25 @@ lsvault publish-vault unpublish vault_abc123
 | Command | Description |
 |---------|-------------|
 | `lsvault hooks list <vaultId>` | List vault hooks |
-| `lsvault hooks create <vaultId>` | Create a new hook |
-| `lsvault hooks update <hookId>` | Update hook configuration |
-| `lsvault hooks delete <hookId>` | Delete a hook |
-| `lsvault webhooks list` | List all webhooks |
-| `lsvault webhooks create` | Create a new webhook |
-| `lsvault webhooks update <webhookId>` | Update webhook configuration |
-| `lsvault webhooks delete <webhookId>` | Delete a webhook |
+| `lsvault hooks create <vaultId> <name>` | Create a new hook |
+| `lsvault hooks delete <vaultId> <hookId>` | Delete a hook |
+| `lsvault hooks executions <vaultId> <hookId>` | View hook execution history |
+| `lsvault webhooks list <vaultId>` | List vault webhooks |
+| `lsvault webhooks create <vaultId> <url>` | Create a new webhook |
+| `lsvault webhooks update <vaultId> <webhookId>` | Update webhook configuration |
+| `lsvault webhooks delete <vaultId> <webhookId>` | Delete a webhook |
 
 **Example:**
 ```bash
-# Create an auto-tag hook
-lsvault hooks create vault_abc123 \
-  --type auto-tag \
-  --config '{"patterns":{"meeting":"#meeting"}}'
+# Create a hook that runs an AI prompt on document creation
+lsvault hooks create vault_abc123 "Auto-tag" \
+  --trigger document.created \
+  --action ai_prompt \
+  --config '{"prompt":"Suggest tags"}'
 
 # Create a webhook for document updates
-lsvault webhooks create \
-  --url https://api.example.com/webhook \
-  --events document.created,document.updated \
-  --secret webhook_secret_key
+lsvault webhooks create vault_abc123 https://api.example.com/webhook \
+  --events document.created,document.updated
 ```
 
 ### Calendar
@@ -414,10 +419,11 @@ lsvault webhooks create \
 |---------|-------------|
 | `lsvault calendar view <vaultId>` | Browse calendar views and activity heatmap |
 | `lsvault calendar due <vaultId>` | List documents by due date |
+| `lsvault calendar set-due <vaultId> <path> --date <date>` | Set or clear a document due date (pass `--date clear` to clear) |
 | `lsvault calendar events <vaultId>` | List calendar events |
-| `lsvault calendar create-event <vaultId>` | Create a calendar event |
-| `lsvault calendar update-event <vaultId> <eventId>` | Update a calendar event |
-| `lsvault calendar delete-event <vaultId> <eventId>` | Delete a calendar event |
+| `lsvault calendar event create <vaultId> <title>` | Create a calendar event |
+| `lsvault calendar event update <vaultId> <eventId>` | Update a calendar event |
+| `lsvault calendar event delete <vaultId> <eventId>` | Delete a calendar event |
 
 ### Booking Commands
 
@@ -638,13 +644,13 @@ Manage multiple configurations with profiles:
 # List profiles
 lsvault config profiles
 
-# Create a profile
-lsvault config create-profile production --api-url https://vault.lifestreamdynamics.com
+# Create a profile by setting a value in it (profiles are created on first use)
+lsvault config set apiUrl https://vault.lifestreamdynamics.com --profile production
 
 # Switch profiles
 lsvault config use production
 
-# Set config values
+# Set config values (in the active profile)
 lsvault config set apiUrl https://vault.lifestreamdynamics.com
 
 # Get config values
@@ -759,12 +765,13 @@ lsvault sync watch sync_xyz789
 lsvault search "quarterly report" --vault vault_abc123 -o json
 
 # Create a share link for the found document
-lsvault shares create vault_abc123 /reports/Q4-2025.md \
-  --password secure123 \
-  --expires-in 30d
+lsvault shares create vault_abc123 reports/Q4-2025.md \
+  --permission view \
+  --protect-with-password \
+  --expires 2026-01-31
 
 # Publish a document publicly
-lsvault publish create vault_abc123 /blog/announcement.md \
+lsvault publish create vault_abc123 blog/announcement.md \
   --slug new-features-2026
 ```
 
@@ -772,30 +779,27 @@ lsvault publish create vault_abc123 /blog/announcement.md \
 
 ```bash
 # Create a team
-lsvault teams create --name "Product Team" --description "Product docs"
+lsvault teams create "Product Team" --description "Product docs"
 
 # Create a vault
 lsvault vaults create "Product Docs" --description "Product documentation"
 
 # Invite team members
-lsvault teams invite team_abc123 --email pm@example.com --role admin
-lsvault teams invite team_abc123 --email dev@example.com --role member
+lsvault teams invitations create team_abc123 pm@example.com --role admin
+lsvault teams invitations create team_abc123 dev@example.com --role editor
 
-# Configure webhook for team updates
-lsvault webhooks create \
-  --url https://slack.example.com/webhook \
-  --events document.created,document.updated \
-  --filter '{"vaultId":"vault_xyz789"}'
+# Configure a webhook for vault updates
+lsvault webhooks create vault_xyz789 https://slack.example.com/webhook \
+  --events document.created,document.updated
 ```
 
 ### Automation with API Keys
 
 ```bash
 # Create a read-only API key for monitoring
-lsvault keys create \
-  --name "Monitoring Script" \
-  --scopes vaults:read,documents:read \
-  --expires-in 90d
+lsvault keys create "Monitoring Script" \
+  --scopes read \
+  --expires 2026-12-31
 
 # Use API key in scripts
 export LSVAULT_API_KEY=lsv_k_generated_key

package/dist/commands/sync.js

@@ -9,7 +9,7 @@ import { formatUptime } from '../utils/format.js';
 import { loadSyncConfigs, createSyncConfig, deleteSyncConfig, getSyncConfig, } from '../sync/config.js';
 import { deleteSyncState, loadSyncState, saveSyncState, hashFileContent, buildRemoteFileState } from '../sync/state.js';
 import { resolveIgnorePatterns } from '../sync/ignore.js';
-import { scanLocalFiles, scanRemoteFiles, executePull, executePush, computePullDiff, computePushDiff, resolveConcurrency, } from '../sync/engine.js';
+import { scanLocalFiles, scanRemoteFiles, executePull, executePush, computePullDiff, computePushDiff, resolveConcurrency, sweepOrphanedTempFiles, } from '../sync/engine.js';
 import { formatDiff } from '../sync/diff.js';
 import { createWatcher } from '../sync/watcher.js';
 import { createRemotePoller } from '../sync/remote-poller.js';
@@ -168,6 +168,11 @@ Sync modes:
             const client = await getClientAsync();
             const ignorePatterns = resolveIgnorePatterns(config.ignore, config.localPath);
             const lastState = loadSyncState(config.id);
+            // Clean up any orphaned temp files left by a prior interrupted pull.
+            const swept = sweepOrphanedTempFiles(config.localPath);
+            if (swept > 0) {
+                out.debug(`Removed ${swept} orphaned temp file(s) from ${config.localPath}`);
+            }
             out.startSpinner('Scanning local files...');
             const localFiles = scanLocalFiles(config.localPath, ignorePatterns, lastState);
             out.debug(`Found ${Object.keys(localFiles).length} local files`);

package/dist/sync/atomic-write.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Write `content` to `targetPath` atomically.
+ *
+ * A uniquely named temp file is created alongside the target.  On success it
+ * is renamed to the target (atomic on POSIX).  If the write or rename throws,
+ * the temp file is best-effort deleted before the original error is re-thrown,
+ * guaranteeing no orphaned `.tmp.<hash>` files are left behind.
+ */
+export declare function atomicWriteFileSync(targetPath: string, content: string, encoding?: BufferEncoding): void;
+/**
+ * Recursively walk `rootDir` and delete orphaned temp files.
+ *
+ * A temp file is considered orphaned when its canonical counterpart — the
+ * path with the `.tmp[.<hash>]` suffix stripped — already exists on disk.
+ * This guard ensures only leftover cruft is removed, never unique content.
+ *
+ * Dirs named `.git`, `node_modules`, or starting with `.` (hidden dirs) and
+ * the `.lsvault` dir are skipped, matching the sync engine's own exclusions.
+ *
+ * Any individual fs error (unreadable dir, permission denied, etc.) is caught
+ * and skipped so a single bad entry cannot abort the sweep.
+ *
+ * @returns the number of orphaned temp files deleted.
+ */
+export declare function sweepOrphanedTempFiles(rootDir: string): number;

package/dist/sync/atomic-write.js

@@ -0,0 +1,98 @@
+/**
+ * Atomic file-write helpers shared by the sync engine and remote poller.
+ *
+ * All writes use a temp-file + rename strategy so interrupted writes never
+ * leave a partial file at the target path.  On any error the temp file is
+ * cleaned up before the error is re-thrown.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+/**
+ * Write `content` to `targetPath` atomically.
+ *
+ * A uniquely named temp file is created alongside the target.  On success it
+ * is renamed to the target (atomic on POSIX).  If the write or rename throws,
+ * the temp file is best-effort deleted before the original error is re-thrown,
+ * guaranteeing no orphaned `.tmp.<hash>` files are left behind.
+ */
+export function atomicWriteFileSync(targetPath, content, encoding = 'utf-8') {
+    const tmpFile = targetPath + '.tmp.' + randomBytes(4).toString('hex');
+    try {
+        fs.writeFileSync(tmpFile, content, encoding);
+        fs.renameSync(tmpFile, targetPath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            // Ignore — the file may not exist if writeFileSync was what threw.
+        }
+        throw err;
+    }
+}
+/**
+ * Regex that matches both forms of orphaned temp-file suffix:
+ *   - `.tmp`           (static suffix used by the legacy inline write in remote-poller)
+ *   - `.tmp.<8hex>`    (randomised suffix used by atomicWriteFileSync)
+ */
+const ORPHAN_TEMP_RE = /\.tmp(\.[0-9a-f]{8})?$/;
+/**
+ * Recursively walk `rootDir` and delete orphaned temp files.
+ *
+ * A temp file is considered orphaned when its canonical counterpart — the
+ * path with the `.tmp[.<hash>]` suffix stripped — already exists on disk.
+ * This guard ensures only leftover cruft is removed, never unique content.
+ *
+ * Dirs named `.git`, `node_modules`, or starting with `.` (hidden dirs) and
+ * the `.lsvault` dir are skipped, matching the sync engine's own exclusions.
+ *
+ * Any individual fs error (unreadable dir, permission denied, etc.) is caught
+ * and skipped so a single bad entry cannot abort the sweep.
+ *
+ * @returns the number of orphaned temp files deleted.
+ */
+export function sweepOrphanedTempFiles(rootDir) {
+    let removed = 0;
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            try {
+                if (entry.isDirectory()) {
+                    // Skip hidden dirs, node_modules, .lsvault
+                    if (entry.name.startsWith('.') ||
+                        entry.name === 'node_modules') {
+                        continue;
+                    }
+                    walk(fullPath);
+                }
+                else if (entry.isFile() && ORPHAN_TEMP_RE.test(entry.name)) {
+                    // Derive the canonical sibling path by stripping the temp suffix.
+                    const canonical = fullPath.replace(ORPHAN_TEMP_RE, '');
+                    if (fs.existsSync(canonical)) {
+                        try {
+                            fs.unlinkSync(fullPath);
+                            removed++;
+                        }
+                        catch {
+                            // Ignore individual unlink failures.
+                        }
+                    }
+                }
+            }
+            catch {
+                // Ignore stat/access errors for individual entries.
+            }
+        }
+    }
+    walk(rootDir);
+    return removed;
+}

package/dist/sync/daemon-worker.js

@@ -10,7 +10,7 @@ import { createRemotePoller } from './remote-poller.js';
 import { removePid } from './daemon.js';
 import { loadConfigAsync } from '../config.js';
 import { LifestreamVaultClient } from '@lifestreamdynamics/vault-sdk';
-import { scanLocalFiles, scanRemoteFiles, computePushDiff, computePullDiff, executePush, executePull } from './engine.js';
+import { scanLocalFiles, scanRemoteFiles, computePushDiff, computePullDiff, executePush, executePull, sweepOrphanedTempFiles } from './engine.js';
 import { loadSyncState, saveSyncState } from './state.js';
 const managed = [];
 function log(msg) {
@@ -43,6 +43,18 @@ async function start() {
         process.exit(0);
     }
     log(`Found ${configs.length} auto-sync configuration(s)`);
+    // One-time orphan sweep: remove any temp files left by prior interrupted pulls.
+    for (const config of configs) {
+        try {
+            const swept = sweepOrphanedTempFiles(config.localPath);
+            if (swept > 0) {
+                log(`Swept ${swept} orphaned temp file(s) from ${config.localPath}`);
+            }
+        }
+        catch {
+            // Non-fatal — continue startup.
+        }
+    }
     const client = await createClient();
     // Startup reconciliation: catch changes made while daemon was stopped
     for (const config of configs) {

package/dist/sync/diff.d.ts

@@ -16,6 +16,12 @@ export interface SyncDiffEntry {
     sizeBytes: number;
     /** Human-readable reason for this change */
     reason: string;
+    /**
+     * SHA-256 hash of the remote file at diff-computation time.
+     * Present on download entries so executePull can issue a conditional GET
+     * (If-None-Match) and skip the write when the local file is already current.
+     */
+    remoteHash?: string;
 }
 export interface SyncDiff {
     /** Files to upload (local -> remote) */

package/dist/sync/diff.js

@@ -19,6 +19,7 @@ export function computePullDiff(localFiles, remoteFiles, lastState) {
                     direction: 'download',
                     sizeBytes: remote.size,
                     reason: 'Deleted locally, exists remotely (pull restores)',
+                    remoteHash: remote.hash,
                 });
             }
             else {
@@ -29,6 +30,7 @@ export function computePullDiff(localFiles, remoteFiles, lastState) {
                     direction: 'download',
                     sizeBytes: remote.size,
                     reason: 'New remote file',
+                    remoteHash: remote.hash,
                 });
             }
         }
@@ -40,6 +42,7 @@ export function computePullDiff(localFiles, remoteFiles, lastState) {
                 direction: 'download',
                 sizeBytes: remote.size,
                 reason: 'Remote file updated',
+                remoteHash: remote.hash,
             });
         }
         else if (!lastRemote && remote.hash !== local.hash) {
@@ -50,6 +53,7 @@ export function computePullDiff(localFiles, remoteFiles, lastState) {
                 direction: 'download',
                 sizeBytes: remote.size,
                 reason: 'Content differs (first sync, pull prefers remote)',
+                remoteHash: remote.hash,
             });
         }
     }

package/dist/sync/engine.d.ts

@@ -1,6 +1,8 @@
 import type { LifestreamVaultClient } from '@lifestreamdynamics/vault-sdk';
 import type { SyncConfig, SyncState, FileState } from './types.js';
 import { computePullDiff, computePushDiff, type SyncDiff, type SyncDiffEntry } from './diff.js';
+import { sweepOrphanedTempFiles } from './atomic-write.js';
+export { sweepOrphanedTempFiles };
 export interface SyncProgress {
     phase: 'scanning' | 'computing' | 'transferring' | 'complete';
     current: number;

package/dist/sync/engine.js

@@ -3,11 +3,12 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { randomBytes } from 'node:crypto';
 import { loadSyncState, saveSyncState, hashFileContent, buildRemoteFileState } from './state.js';
 import { updateLastSync } from './config.js';
 import { shouldIgnore } from './ignore.js';
 import { computePullDiff, computePushDiff } from './diff.js';
+import { atomicWriteFileSync, sweepOrphanedTempFiles } from './atomic-write.js';
+export { sweepOrphanedTempFiles };
 /**
  * Scan local directory recursively for .md files.
  * Returns a map of relative doc paths -> FileState.
@@ -110,15 +111,6 @@ export async function scanRemoteFiles(client, vaultId, ignorePatterns, knownStat
     }
     return { files, listEtag: sync.listEtag, vaultUnchanged: false };
 }
-/**
- * Write a file atomically using a temp file + rename.
- * Prevents partial reads if the process is interrupted mid-write.
- */
-function atomicWriteFileSync(targetPath, content, encoding = 'utf-8') {
-    const tmpFile = targetPath + '.tmp.' + randomBytes(4).toString('hex');
-    fs.writeFileSync(tmpFile, content, encoding);
-    fs.renameSync(tmpFile, targetPath);
-}
 /**
  * Default in-flight transfer count. A small number flattens the load1 spike
  * a full-vault `sync pull` causes on the API host without making single
@@ -249,9 +241,27 @@ export async function executePull(client, config, diff, onProgress, concurrency,
         deletes: diff.deletes,
         transferCounterKey: 'filesDownloaded',
         async transferFile(entry, cfg, throttleCallback) {
-            const { content } = await retryWithBackoff(() => client.documents.get(cfg.vaultId, entry.path), throttleCallback ? () => throttleCallback(entry.path) : undefined);
             const localFile = path.join(cfg.localPath, entry.path);
             const localDir = path.dirname(localFile);
+            // Only use a conditional GET when (a) we have the remote hash AND (b)
+            // the local file already exists.  For 'create' entries the local file
+            // does not exist yet — the server will always 304 (our remoteHash IS the
+            // server's current hash), which would send the 304 branch into a
+            // readFileSync on a non-existent path (ENOENT).  Guarding on existsSync
+            // also makes the readFileSync in the 304 branch provably safe.
+            const useConditional = entry.remoteHash !== undefined && fs.existsSync(localFile);
+            const result = await retryWithBackoff(() => useConditional
+                ? client.documents.get(cfg.vaultId, entry.path, { ifNoneMatch: `"${entry.remoteHash}"` })
+                : client.documents.get(cfg.vaultId, entry.path), throttleCallback ? () => throttleCallback(entry.path) : undefined);
+            // 304 Not Modified — local already has the right content; skip the write.
+            // Safe: only reached when useConditional === true, which requires the
+            // local file to exist.
+            if ('notModified' in result && result.notModified) {
+                const localContent = fs.readFileSync(localFile, 'utf-8');
+                return localContent;
+            }
+            // 200 response — result has `content` (handle both shapes of the union).
+            const content = result.content;
             if (!fs.existsSync(localDir)) {
                 fs.mkdirSync(localDir, { recursive: true });
             }

package/dist/sync/ignore.js

@@ -12,6 +12,7 @@ export const DEFAULT_IGNORE_PATTERNS = [
     '.hg/',
     'node_modules/',
     '*.tmp',
+    '*.tmp.*',
     '.DS_Store',
     'Thumbs.db',
     '.lsvault/',

package/dist/sync/remote-poller.js

@@ -9,6 +9,7 @@ import { loadSyncState, saveSyncState, hashFileContent, buildRemoteFileState } f
 import { updateLastSync } from './config.js';
 import { resolveConflict, detectConflict, createConflictFile, formatConflictLog } from './conflict.js';
 import { isThrottleError } from './engine.js';
+import { atomicWriteFileSync } from './atomic-write.js';
 /**
  * Creates and starts a remote poller for a sync configuration.
  * Returns a stop function.
@@ -92,9 +93,7 @@ export function createRemotePoller(client, config, options) {
                         if (resolution === 'remote') {
                             conflictFile = createConflictFile(config.localPath, change.path, localContent, 'local');
                             onLocalWrite?.(change.path);
-                            const tmpConflict = localFile + '.tmp';
-                            fs.writeFileSync(tmpConflict, content, 'utf-8');
-                            fs.renameSync(tmpConflict, localFile);
+                            atomicWriteFileSync(localFile, content, 'utf-8');
                             log(`Conflict: ${change.path} — used remote, saved local as ${conflictFile}`);
                         }
                         else {
@@ -118,9 +117,7 @@ export function createRemotePoller(client, config, options) {
                     fs.mkdirSync(dir, { recursive: true });
                 }
                 onLocalWrite?.(change.path);
-                const tmpFile = localFile + '.tmp';
-                fs.writeFileSync(tmpFile, content, 'utf-8');
-                fs.renameSync(tmpFile, localFile);
+                atomicWriteFileSync(localFile, content, 'utf-8');
                 log(`Pulled: ${change.path}`);
                 changes++;
                 state.local[change.path] = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifestreamdynamics/vault-cli",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "Command-line interface for Lifestream Vault",
   "engines": {
     "node": ">=22"