@tenonhq/dovetail-core 0.0.85

package/skills/dove-delete-record.md

@@ -0,0 +1,104 @@
+# Delete ServiceNow Records
+
+## Task
+$ARGUMENTS
+
+## Instructions for Claude
+
+### Directory Context
+
+Dovetail commands can be run from two locations:
+- **From `ServiceNow/` directory:** `npx sinc <command>`
+- **From Craftsman root:** `npm run sinc:<command>` (proxy scripts)
+
+The `delete` command requires running from the `ServiceNow/` directory directly, as it accepts flags and arguments that npm run scripts don't forward.
+
+---
+
+Help the user delete records from a ServiceNow instance using Dovetail's `delete` command. After deletion, local files and the manifest are automatically cleaned up.
+
+### Command Syntax
+
+```bash
+npx dove delete <table> [name] [options]
+```
+
+### Options
+
+| Flag | Alias | Type | Description |
+|------|-------|------|-------------|
+| `--scope` | `-s` | string | Target scope (e.g., x_cadso_core) |
+| `--sysid` | | string | Delete by sys_id directly (skip manifest lookup) |
+| `--ci` | | boolean | Skip confirmation prompt |
+| `--keep-local` | | boolean | Keep local files after instance delete |
+
+### Examples
+
+#### Delete by record name (interactive)
+
+```bash
+npx dove delete sys_script_include MyOldUtil
+# Prompts for: scope (if not determinable), confirmation
+```
+
+#### Delete with scope
+
+```bash
+npx dove delete sys_script_include MyOldUtil --scope x_cadso_core
+```
+
+#### Delete by sys_id
+
+```bash
+npx dove delete sys_script_include --sysid abc123def456789012345678901234ab --scope x_cadso_core
+```
+
+#### Delete but keep local files
+
+```bash
+npx dove delete sys_script_include MyOldUtil --scope x_cadso_core --keep-local
+```
+
+#### CI/Automation mode (no prompts)
+
+```bash
+npx dove delete sys_script_include MyOldUtil --scope x_cadso_core --ci
+```
+
+### What Happens After Delete
+
+1. **Record is deleted** from the ServiceNow instance via `api/cadso/dovetail/deleteRecord`
+2. **Local files are removed** — the entire record directory (`src/<scope>/<table>/<name>/`) is deleted
+3. **Manifest is updated** — the record entry is removed from `dove.manifest.<scope>.json`
+4. If the table has no remaining records, the table entry is also removed from the manifest
+
+### How sys_id Resolution Works
+
+When you provide a **record name** (not `--sysid`):
+1. The scope manifest (`dove.manifest.<scope>.json`) is loaded
+2. The sys_id is looked up from `manifest.tables[table].records[name].sys_id`
+3. If not found, an error is shown with a suggestion to use `--sysid`
+
+### Common Table Names
+
+| Table | Deletes |
+|-------|---------|
+| `sys_script_include` | Script Include |
+| `sys_script` | Business Rule |
+| `sys_ui_script` | UI Script |
+| `sys_ui_page` | UI Page |
+| `sys_ux_client_script` | UX Client Script |
+| `sys_processor` | Processor |
+| `sys_ws_operation` | REST API Operation |
+| `sys_rest_message_fn` | REST Message Function |
+| `sys_ui_action` | UI Action |
+| `sysevent_script_action` | Event Script Action |
+
+### Troubleshooting
+
+- **"Record not found in manifest"** — The record isn't tracked locally. Use `--sysid` to delete by sys_id directly, or run `npx dove refresh` first
+- **"Missing required fields: table, sys_id"** — Provide the table as the first argument and either a name or `--sysid`
+- **"Record not found: table/sys_id"** — The record doesn't exist on the instance (may have been deleted already)
+- **"Failed to delete record"** — Check permissions. The user may not have delete access to this table/scope
+- **"Local cleanup failed"** — Record was deleted on instance but local files remain. Run `npx dove refresh` to sync
+- **Deleted wrong record** — Records deleted from ServiceNow cannot be recovered unless they're in an update set that hasn't been committed. Check update set history

package/skills/dove-manage-tables.md

@@ -0,0 +1,174 @@
+# Manage Dovetail Table Includes, Excludes, and Options
+
+## Task
+$ARGUMENTS
+
+## Instructions for Claude
+
+### Directory Context
+
+Dovetail commands can be run from two locations:
+- **From `ServiceNow/` directory:** `npx sinc <command>`
+- **From Craftsman root:** `npm run sinc:<command>` (proxy scripts)
+
+Available root scripts: `sinc:init`, `sinc:start`, `sinc:dev`, `sinc:build`, `sinc:deploy`, `sinc:push`, `sinc:refresh`, `sinc:status`
+
+When this skill references `npx sinc <command>`, use `npm run sinc:<command>` if working from the Craftsman root. Configuration files (`dove.config.js`) live in the `ServiceNow/` directory.
+
+---
+
+Help the user configure which ServiceNow tables and fields Dovetail tracks, and how records are organized locally.
+
+### How Table Filtering Works
+
+Dovetail has a three-layer system:
+
+1. **Default excludes** (built into core) -- Tables excluded by default because they contain non-code metadata
+2. **User `excludes`** in `dove.config.js` -- Additional exclusions or overrides of defaults
+3. **User `includes`** in `dove.config.js` -- Explicit inclusions that override excludes
+
+User config is ADDITIVE to defaults (merged with `Object.assign`).
+
+### Default Excluded Tables
+
+These tables are excluded by default:
+
+```
+sys_scope_privilege, sys_dictionary, sys_impex_entry, sys_security_acl,
+sys_transform_map, sys_ui_policy, sys_ui_list_control, sys_relationship,
+sys_report, item_option_new, sys_process_flow, content_block_programmatic,
+sp_instance, sys_transform_script, sc_category, sysrule_view, sc_cat_item,
+sysevent_in_email_action, sys_navigator, sys_transform_entry,
+metric_definition, content_block_lists, content_block_detail, sp_portal,
+sc_cat_item_producer, sys_impex_map
+```
+
+### Excludes Configuration
+
+```javascript
+// dove.config.js
+module.exports = {
+  excludes: {
+    // Override a default exclusion (RE-INCLUDE the table)
+    sys_scope_privilege: false,
+
+    // Exclude an entire table
+    my_cool_table: true,
+
+    // Exclude specific fields from a table (other fields still included)
+    new_cool_table: {
+      cool_script: true
+    }
+  }
+};
+```
+
+### Includes Configuration
+
+Includes override excludes when there is a conflict on the same table.
+
+```javascript
+// dove.config.js
+module.exports = {
+  includes: {
+    // Override a default inclusion (REMOVE the table)
+    content_css: false,
+
+    // Explicitly include a table (overrides any exclude on same table)
+    sys_report: true,
+
+    // Include a specific field with a custom file type
+    special_code_table: {
+      neat_script_field: {
+        type: "js"
+      }
+    }
+  }
+};
+```
+
+Valid file types: `"js"`, `"css"`, `"xml"`, `"html"`, `"scss"`, `"txt"`, `"json"`
+
+### Table Options
+
+The `tableOptions` section controls how records are organized on disk:
+
+```javascript
+// dove.config.js
+module.exports = {
+  tableOptions: {
+    some_table: {
+      // Use a different field for the record folder name
+      displayField: "some_field",
+
+      // De-duplicate records with the same display value
+      differentiatorField: "sys_id",
+
+      // Can be an array -- falls back to next field if first is empty
+      differentiatorField: ["some_field", "sys_id"],
+
+      // Filter records with an encoded query
+      query: "active=true^category=scripts"
+    }
+  }
+};
+```
+
+### After Changing Configuration
+
+1. Run `npx dove refresh` to update the manifest with new tables/fields
+2. Manually delete any folders for tables you just excluded (Dovetail does not auto-delete)
+3. New tables/fields will be downloaded automatically by refresh
+
+### Common Recipes
+
+**Track only script-related tables:**
+```javascript
+includes: {
+  sys_script_include: true,
+  sys_script: true,
+  sys_ui_script: true,
+  sys_ui_page: true,
+  sp_widget: true
+}
+```
+
+**Include a non-code field as code:**
+```javascript
+includes: {
+  sys_ui_page: {
+    html: { type: "html" },
+    client_script: { type: "js" },
+    processing_script: { type: "js" }
+  }
+}
+```
+
+**Filter records by query:**
+```javascript
+tableOptions: {
+  sys_script_include: {
+    query: "active=true"
+  }
+}
+```
+
+### Scope-Specific Configuration
+
+When using multi-scope mode, each scope can have its own `tableOptions`:
+
+```javascript
+module.exports = {
+  tableOptions: { /* default table options */ },
+  scopes: {
+    x_cadso_core: {
+      sourceDirectory: "src/x_cadso_core",
+      tableOptions: {
+        sys_script_include: {
+          query: "active=true"
+        }
+      }
+    }
+  }
+};
+```

package/skills/dove-manage-update-sets.md

@@ -0,0 +1,88 @@
+# Manage ServiceNow Update Sets
+
+## Task
+$ARGUMENTS
+
+## Instructions for Claude
+
+### Directory Context
+
+Dovetail commands can be run from two locations:
+- **From `ServiceNow/` directory:** `npx sinc <command>`
+- **From Craftsman root:** `npm run sinc:<command>` (proxy scripts)
+
+Available root scripts: `sinc:init`, `sinc:start`, `sinc:dev`, `sinc:build`, `sinc:deploy`, `sinc:push`, `sinc:refresh`, `sinc:status`
+
+When this skill references `npx sinc <command>`, use `npm run sinc:<command>` if working from the Craftsman root. Note: commands with extra flags (e.g., `npx dove push --updateSet "name"`) require running from the `ServiceNow/` directory directly, as npm run scripts don't forward arguments.
+
+---
+
+Help the user manage ServiceNow update sets through Dovetail's CLI commands and dashboard.
+
+### Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npx dove listUpdateSets` | List all in-progress update sets |
+| `npx dove listUpdateSets --scope x_cadso_core` | List update sets for a specific scope |
+| `npx dove createUpdateSet --name "FEAT-123 New Feature"` | Create and activate a new update set |
+| `npx dove createUpdateSet --name "FEAT-123" --scope x_cadso_core --description "Feature description"` | Create with scope and description |
+| `npx dove switchUpdateSet --name "FEAT-123"` | Switch to an existing update set (partial name match) |
+| `npx dove switchUpdateSet --scope x_cadso_core` | Browse and select from a scope's update sets |
+| `npx dove currentUpdateSet` | Show the currently active update set |
+| `npx dove currentScope` | Show the currently active scope |
+| `npx dove changeScope --scope x_cadso_work` | Switch to a different scope |
+
+### Push with Update Set
+
+Create a new update set as part of a push operation:
+
+```bash
+npx dove push --updateSet "FEAT-123 My Changes"
+# or short form:
+npx dove push --us "FEAT-123 My Changes"
+```
+
+This creates the update set, assigns it as current, and pushes all files into it.
+
+### Web Dashboard
+
+Dovetail includes a web dashboard for visual update set management:
+
+```bash
+npx dove dashboard
+```
+
+Launches at `http://localhost:3456` (configurable via `DASHBOARD_PORT` in `.env`). Features:
+- All configured scopes with display names
+- In-progress update sets per scope
+- Create new update sets
+- Close (complete) update sets
+- Select active update set per scope
+
+The dashboard reads scopes from `dove.config.js` and stores selections in `.dove-update-sets.json`.
+
+### Multi-Scope Update Set Monitoring
+
+When using `npx dove watchAllScopes`, update set status is automatically checked every 2 minutes. It warns if any scope is using the DEFAULT update set (a common mistake that puts changes in the wrong place).
+
+### Recommended Workflow
+
+1. **Before starting work:** Create a named update set for your feature/ticket:
+   ```bash
+   npx dove createUpdateSet --name "FEAT-123 Add User Dashboard" --scope x_cadso_core
+   ```
+
+2. **During development:** Use `npx dove dev` or `npx dove watchAllScopes`. Changes go into the active update set.
+
+3. **Check status:** `npx dove currentUpdateSet` to verify you are in the right update set.
+
+4. **When done:** Complete the update set in ServiceNow or via the dashboard.
+
+5. **For deployment:** Use `npx dove push --us "RELEASE-1.0"` to push all changes into a clean update set.
+
+### Common Issues
+
+- **"No update set selected"** -- You are using the Default update set. Create or switch to a named one.
+- **Changes going to wrong scope** -- In multi-scope mode, use `npx dove watchAllScopes` which auto-switches scopes. Single-scope `npx dove dev` only works for one scope.
+- **Update set not found** -- Check the scope filter. Update sets are scope-specific.

package/skills/dove-setup-project.md

@@ -0,0 +1,154 @@
+# Set Up Dovetail Project
+
+## Task
+$ARGUMENTS
+
+## Instructions for Claude
+
+### Directory Context
+
+Dovetail commands can be run from two locations:
+- **From `ServiceNow/` directory:** `npx sinc <command>`
+- **From Craftsman root:** `npm run sinc:<command>` (proxy scripts)
+
+Available root scripts: `sinc:init`, `sinc:start`, `sinc:dev`, `sinc:build`, `sinc:deploy`, `sinc:push`, `sinc:refresh`, `sinc:status`
+
+When this skill references `npx sinc <command>`, use `npm run sinc:<command>` if working from the Craftsman root. Configuration files (`dove.config.js`, `.env`, manifests) live in the `ServiceNow/` directory.
+
+---
+
+Help the user set up a new Dovetail project or add a new scope to an existing project.
+
+### Determine the Scenario
+
+1. **New project from scratch** -- No `dove.config.js` exists yet
+2. **Add a new scope to existing project** -- `dove.config.js` exists, need to add scope config
+3. **Re-initialize / reset** -- Project exists but needs fresh download
+
+### Scenario 1: New Project
+
+#### Prerequisites check
+- Node.js v20 LTS installed (`node -v`)
+- The Dovetail server scoped app is installed on the target ServiceNow instance
+
+#### Initialize the project
+```bash
+mkdir my-servicenow-app && cd my-servicenow-app
+npm init -y
+npm i -D @tenonhq/dovetail-core
+```
+
+#### Run the init wizard
+```bash
+npx dove init
+```
+Prompts for: instance URL, username, password, and which scoped app to download.
+
+#### Configure the build pipeline
+Direct the user to use the `configure-pipeline` skill or help inline.
+
+#### Set up `.env`
+```
+SN_USER=admin
+SN_PASSWORD=your_password
+SN_INSTANCE=your-instance.service-now.com
+```
+- Instance should NOT have `https://` prefix or trailing slash
+- Optional: `DASHBOARD_PORT=3456`
+- **Never commit `.env` to git**
+
+#### Set up `.gitignore`
+```
+node_modules/
+.env
+build/
+dove.manifest*.json
+dovetail-debug-*.log
+```
+
+#### Start development
+```bash
+npx dove dev
+```
+
+### Scenario 2: Add a New Scope (Multi-Scope Setup)
+
+#### Add the scope to `dove.config.js`
+```javascript
+module.exports = {
+  sourceDirectory: "src",
+  buildDirectory: "build",
+  rules: [ /* ... */ ],
+  scopes: {
+    x_cadso_core: {
+      sourceDirectory: "src/x_cadso_core"
+    },
+    x_cadso_work: {
+      sourceDirectory: "src/x_cadso_work"
+    }
+  }
+};
+```
+
+#### Download all scopes
+```bash
+npx dove initScopes
+```
+Creates per-scope manifest files (`dove.manifest.x_cadso_core.json`, etc.) and downloads files to each scope's source directory.
+
+If hitting rate limits:
+```bash
+npx dove initScopes --delay 1000
+```
+
+#### Watch all scopes simultaneously
+```bash
+npx dove watchAllScopes
+```
+Watches all scope directories, auto-switches ServiceNow scope context per file, monitors update set status every 2 minutes.
+
+#### Download a single scope
+```bash
+npx dove download x_cadso_core
+```
+
+### Scenario 3: Reset / Re-download
+
+1. Back up any local changes (commit to git)
+2. Run: `npx dove download <scope>` (destructive -- overwrites local files)
+3. Or for all scopes: `npx dove initScopes`
+
+### File Structure After Setup
+
+```
+project/
+  .env                              # Credentials (git-ignored)
+  dove.config.js                    # Build pipeline config
+  dove.manifest.json                # Single-scope manifest
+  dove.manifest.x_cadso_core.json   # Multi-scope manifest
+  src/
+    x_cadso_core/
+      sys_script_include/
+        MyScriptInclude/
+          script.ts
+      sys_ui_page/
+        MyUIPage/
+          html.html
+          client_script.js
+    x_cadso_work/
+      ...
+  build/                            # Built output (git-ignored)
+  node_modules/                     # Dependencies (git-ignored)
+```
+
+### Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `npx dove init` | Interactive project setup |
+| `npx dove initScopes` | Download all configured scopes |
+| `npx dove download <scope>` | Download a specific scope (destructive) |
+| `npx dove refresh` | Refresh manifest, download new files only |
+| `npx dove dev` | Start single-scope watch mode |
+| `npx dove watchAllScopes` | Start multi-scope watch mode |
+| `npx dove status` | Show connected instance, scope, user |

package/skills/dove-troubleshoot-sync.md

@@ -0,0 +1,113 @@
+# Troubleshoot Dovetail Sync Issues
+
+## Task
+$ARGUMENTS
+
+## Instructions for Claude
+
+### Directory Context
+
+Dovetail commands can be run from two locations:
+- **From `ServiceNow/` directory:** `npx sinc <command>`
+- **From Craftsman root:** `npm run sinc:<command>` (proxy scripts)
+
+Available root scripts: `sinc:init`, `sinc:start`, `sinc:dev`, `sinc:build`, `sinc:deploy`, `sinc:push`, `sinc:refresh`, `sinc:status`
+
+When this skill references `npx sinc <command>`, use `npm run sinc:<command>` if working from the Craftsman root. References to "project root" mean the `ServiceNow/` directory (where `dove.config.js`, `.env`, and manifest files live).
+
+---
+
+Help the user diagnose and fix Dovetail synchronization problems. Follow this systematic diagnostic approach.
+
+### Step 1: Identify the Symptom Category
+
+Ask the user which symptom they are experiencing (if not already clear):
+
+- **A. Files not pushing** -- saves detected but nothing reaches ServiceNow
+- **B. Authentication/connection failure** -- errors about credentials or instance
+- **C. Scope mismatch** -- "scope check failed" errors
+- **D. Build/transform errors** -- plugin pipeline failures
+- **E. Missing files** -- files exist in ServiceNow but not locally (or vice versa)
+- **F. Manifest corruption** -- strange behavior, duplicate records, wrong sys_ids
+
+### Diagnostic A: Files Not Pushing
+
+1. **Check dev mode is running:** `npx dove dev` or `npx dove watchAllScopes`
+2. **Check the file is in the manifest:** Look in `dove.manifest.json` or `dove.manifest.<scope>.json` for the table/record/field entry. If missing, run `npx dove refresh`.
+3. **Check file extension matches a rule:** The file extension must match a `match` regex in `dove.config.js` rules. If no rule matches, the file content is pushed as-is (no build).
+4. **Check debug logs:** Look for `dovetail-debug-*.log` files in the project root.
+5. **Try manual push:** `npx dove push` to push all files and see errors.
+
+### Diagnostic B: Authentication/Connection Failure
+
+1. **Verify `.env` file exists** in the project root with correct values:
+   ```
+   SN_USER=your_username
+   SN_PASSWORD=your_password
+   SN_INSTANCE=your-instance.service-now.com
+   ```
+   - Instance should NOT have `https://` prefix or trailing slash
+   - Credentials must have admin or developer role
+
+2. **Test connection:** `npx dove status`
+
+3. **Check the Dovetail server scoped app** is installed on the instance. Without it, API endpoints will 404.
+
+4. **Check for MFA/SSO:** If the instance uses MFA or SSO, basic auth may not work. You may need a local ServiceNow account.
+
+### Diagnostic C: Scope Mismatch
+
+Dovetail checks that your local manifest scope matches the active scope on the ServiceNow instance.
+
+1. **Check current scope:** `npx dove currentScope`
+2. **Change scope:** `npx dove changeScope --scope x_cadso_core`
+3. **For multi-scope watch:** `npx dove watchAllScopes` handles scope switching automatically per file.
+4. **Force scope swap on push:** `npx dove push --scopeSwap`
+
+### Diagnostic D: Build/Transform Errors
+
+1. **Run a local build to see errors:** `npx dove build`
+2. **Common Babel errors:**
+   - "Cannot find module '@tenonhq/dovetail-remove-modules'" -- Need `npm i -D @tenonhq/dovetail-babel-plugin-remove-modules`
+   - "Cannot find module '@tenonhq/dovetail-servicenow'" -- Need `npm i -D @tenonhq/dovetail-babel-preset-servicenow`
+   - Note: Babel package names differ from dove.config.js names. In Babel config, `@tenonhq/dovetail-remove-modules` refers to npm package `@tenonhq/dovetail-babel-plugin-remove-modules`.
+
+3. **Common TypeScript errors:**
+   - Type errors block the build. Fix the types or set `transpile: true` to skip type checking.
+   - Missing `tsconfig.json` -- Plugin works without it but may produce unexpected output.
+
+4. **Rhino engine errors (code works locally but fails in ServiceNow):**
+   - Missing `@tenonhq/dovetail-servicenow` preset -- `__proto__` references and reserved word property access crash Rhino.
+   - Using `useBuiltIns` with `@babel/env` -- Polyfills fail because Rhino locks base class prototypes.
+   - Using `for...of`, `Map`, `Set`, `WeakMap` -- These require prototype extensions that Rhino blocks.
+   - Using arrow functions in class properties without `@babel/proposal-class-properties`.
+
+### Diagnostic E: Missing Files
+
+1. **Files in ServiceNow but not local:**
+   - Run `npx dove refresh` to update the manifest and download new files.
+   - Check `excludes` in `dove.config.js` -- the table may be excluded.
+   - Check `includes` -- some tables need explicit inclusion.
+
+2. **Files local but not in ServiceNow:**
+   - Records must be created in ServiceNow first, then `npx dove refresh` to pick them up.
+   - Dovetail does NOT create ServiceNow records from local files.
+
+### Diagnostic F: Manifest Corruption
+
+1. **Symptoms:** Wrong files being pushed, duplicate record folders, sys_id mismatches.
+2. **Fix:** Delete the manifest file(s) and re-download:
+   ```bash
+   rm dove.manifest*.json
+   npx dove download <scope>
+   # or for multi-scope:
+   npx dove initScopes
+   ```
+3. **Prevention:** Never manually edit `dove.manifest.json`. Never have duplicate record display values in the same table.
+
+### General Tips
+
+- Always `npx dove refresh` before starting work to catch new records.
+- Use `npx dove status` to verify connectivity.
+- Check `dovetail-debug-*.log` for detailed error information.
+- Node.js v20 LTS is required -- check with `node -v`.