permcraft 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akif
+
+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,350 @@
+# Permcraft
+
+Interactive CLI tool that lets Salesforce developers manage permission set XML files without manually editing XML. Express your permission intent once, and Permcraft applies it across multiple permission sets.
+
+## What it does
+
+- Fetches objects and fields from your connected Salesforce org
+- Lets you search and select objects/fields using fuzzy search
+- Assigns object permissions (Read, Create, Edit, Delete, View All, Modify All) and field permissions (Read, Edit)
+- Applies selected permissions to one or more local `.permissionset-meta.xml` files
+- Automatically enforces permission dependencies (e.g., selecting Edit auto-enables Read)
+- Supports two permission modes: **Bulk** (same permissions across all selections) and **Granular** (different permissions per object/field)
+- Never downgrades existing permissions — only adds or upgrades
+
+## Prerequisites
+
+- **Node.js** (LTS version)
+- **Salesforce CLI (`sf`)** installed and available in your PATH
+- An **authenticated Salesforce org** connected via `sf org login web`
+- Must be run inside a **Salesforce DX project** (directory containing `sfdx-project.json`)
+
+## Installation
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd salesforce-permission-cli
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Link globally so "permcraft" is available anywhere
+npm link
+```
+
+## Usage
+
+Navigate to your SFDX project directory and run:
+
+```bash
+permcraft
+```
+
+### Options
+
+```
+-h, --help     Show help message
+-v, --version  Show version number
+```
+
+### Uninstalling
+
+To remove the global `permcraft` command:
+
+```bash
+cd /path/to/salesforce-permission-cli
+npm unlink permcraft
+```
+
+## Walkthrough
+
+### Example 1: Bulk mode — same permissions for multiple objects
+
+```
+$ permcraft
+
+Permcraft — Salesforce Permission Set Editor
+
+Checking environment...
+  Project: /Users/dev/my-sfdx-project
+  Org: admin@myorg.com
+
+Fetching objects from org...
+Found 847 objects.
+
+Start typing to search for an object. Select it to add.
+
+? Search for an object: acc
+  Account
+  AccountContactRole
+  AccountTeamMember
+> Account           # user selects Account
+
+  Added: Account
+? Add another object? Yes
+
+? Selected: [Account] — Search for another object (or type "done"): cas
+> Case              # user selects Case
+
+  Added: Case
+? Add another object? No
+
+Selected objects: Account, Case
+
+Fetching fields for Account...
+Found 72 fields.
+
+Start typing to search for a field on Account.
+
+? Search for a field on Account: indus
+> Account.Industry  # user selects Industry
+
+  Added: Account.Industry
+? Add another field? No
+
+Fetching fields for Case...
+Found 58 fields.
+
+Start typing to search for a field on Case.
+
+? Search for a field on Case: stat
+> Case.Status       # user selects Status
+
+  Added: Case.Status
+? Add another field? No
+
+? How would you like to assign permissions?
+> Bulk — same permissions for all selected objects/fields
+
+? Permissions for 2 objects (Account, Case) (Press <space> to select)
+ [x] Read
+ [x] Create
+ [x] Edit
+ [ ] Delete
+ [ ] View All
+ [ ] Modify All
+
+? Permissions for 2 fields (Press <space> to select)
+ [x] Read
+ [ ] Edit
+
+Scanning local permission sets...
+Found 3 permission sets.
+
+? Select permission sets to update (press <space> to select, <enter> to confirm)
+ [x] Sales_User
+ [x] Support_User
+ [ ] Admin
+
+--- Preview ---
+
+Permission Set: Sales_User
+  + Account: Read, Create, Edit
+  + Case: Read, Create, Edit
+  + Account.Industry: Read
+  + Case.Status: Read
+
+Permission Set: Support_User
+  + Account: Read, Create, Edit
+  + Case: Read, Create, Edit
+  + Account.Industry: Read
+  + Case.Status: Read
+
+? Apply these changes? Yes
+
+Applying changes...
+
+  Updating /Users/dev/my-sfdx-project/force-app/main/default/permissionsets/Sales_User.permissionset-meta.xml
+  Updating /Users/dev/my-sfdx-project/force-app/main/default/permissionsets/Support_User.permissionset-meta.xml
+
+All changes applied successfully!
+```
+
+### Example 2: Granular mode — different permissions per object/field
+
+```
+$ permcraft
+
+Permcraft — Salesforce Permission Set Editor
+
+Checking environment...
+  Project: /Users/dev/my-sfdx-project
+  Org: admin@myorg.com
+
+Fetching objects from org...
+Found 847 objects.
+
+Start typing to search for an object. Select it to add.
+
+? Search for an object: Account
+  Added: Account
+? Add another object? Yes
+? Selected: [Account] — Search for another object (or type "done"): Case
+  Added: Case
+? Add another object? No
+
+Selected objects: Account, Case
+
+Fetching fields for Account...
+Found 72 fields.
+
+Start typing to search for a field on Account.
+
+? Search for a field on Account: Revenue
+  Added: Account.AnnualRevenue
+? Add another field? No
+
+Fetching fields for Case...
+Found 58 fields.
+
+Start typing to search for a field on Case.
+
+? Search for a field on Case: Priority
+  Added: Case.Priority
+? Add another field? No
+
+? How would you like to assign permissions?
+> Granular — different permissions for each object/field
+
+? Permissions for Account
+ [x] Read
+ [x] Create
+ [x] Edit
+ [x] Delete
+ [ ] View All
+ [ ] Modify All
+
+? Permissions for Case
+ [x] Read
+ [x] Create
+ [ ] Edit
+ [ ] Delete
+ [ ] View All
+ [ ] Modify All
+
+? Permissions for Account.AnnualRevenue
+ [x] Read
+ [x] Edit
+
+? Permissions for Case.Priority
+ [x] Read
+ [ ] Edit
+
+Scanning local permission sets...
+Found 2 permission sets.
+
+? Select permission sets to update (press <space> to select, <enter> to confirm)
+ [x] Sales_User
+
+--- Preview ---
+
+Permission Set: Sales_User
+  + Account: Read, Create, Edit, Delete
+  + Case: Read, Create
+  + Account.AnnualRevenue: Read, Edit
+  + Case.Priority: Read
+
+? Apply these changes? Yes
+
+Applying changes...
+
+  Updating /Users/dev/my-sfdx-project/force-app/main/default/permissionsets/Sales_User.permissionset-meta.xml
+
+All changes applied successfully!
+```
+
+### Example 3: Generated XML output
+
+After running permcraft, the permission set XML file is updated cleanly:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <hasActivationRequired>false</hasActivationRequired>
+    <label>Sales_User</label>
+    <objectPermissions>
+        <allowCreate>true</allowCreate>
+        <allowDelete>false</allowDelete>
+        <allowEdit>true</allowEdit>
+        <allowRead>true</allowRead>
+        <modifyAllRecords>false</modifyAllRecords>
+        <object>Account</object>
+        <viewAllRecords>false</viewAllRecords>
+    </objectPermissions>
+    <objectPermissions>
+        <allowCreate>true</allowCreate>
+        <allowDelete>false</allowDelete>
+        <allowEdit>false</allowEdit>
+        <allowRead>true</allowRead>
+        <modifyAllRecords>false</modifyAllRecords>
+        <object>Case</object>
+        <viewAllRecords>false</viewAllRecords>
+    </objectPermissions>
+    <fieldPermissions>
+        <editable>false</editable>
+        <field>Account.Industry</field>
+        <readable>true</readable>
+    </fieldPermissions>
+</PermissionSet>
+```
+
+## Permission dependency rules
+
+Permcraft automatically enforces Salesforce permission dependencies. When you select a permission, all its prerequisites are auto-enabled:
+
+**Object permissions** (each implies all below it):
+
+```
+Modify All → View All → Delete → Edit → Read
+```
+
+**Field permissions:**
+
+```
+Edit → Read
+```
+
+Auto-enabled dependencies are shown in the preview before applying.
+
+## What it supports
+
+- Fuzzy search across all org objects and fields
+- Object-level permissions: Read, Create, Edit, Delete, View All, Modify All
+- Field-level permissions: Read, Edit
+- Bulk and granular permission assignment modes
+- Updating existing permission set XML files
+- Creating new permission set XML files (for permission sets that exist in the org but not locally)
+- Preserving existing permissions (never downgrades)
+- Preserving XML formatting and indentation style of existing files
+- Applying permissions across multiple permission sets in a single session
+
+## What it does not support (yet)
+
+- Non-interactive / CI mode (flags and arguments for scripting)
+- Tab permissions (TabVisibility)
+- Apex class and Visualforce page access
+- Record type assignments
+- Application visibility
+- Custom permission assignments
+- Removing or revoking permissions
+- Profile metadata editing (only permission sets)
+- Deploying changes to the org (use `sf project deploy start` after running permcraft)
+
+## Development
+
+```bash
+npm install       # install dependencies
+npm run build     # compile TypeScript
+npm run dev       # run without building (uses tsx)
+npm test          # run test suite
+npm run lint      # lint source files
+npm run format    # format source files
+```
+
+## License
+
+MIT

package/dist/dependencies.d.ts

@@ -0,0 +1,9 @@
+import type { ObjectPermissions, FieldPermissions } from './types.js';
+export declare function resolveObjectDependencies(perms: ObjectPermissions): {
+    resolved: ObjectPermissions;
+    autoEnabled: string[];
+};
+export declare function resolveFieldDependencies(perms: FieldPermissions): {
+    resolved: FieldPermissions;
+    autoEnabled: string[];
+};

package/dist/dependencies.js

@@ -0,0 +1,51 @@
+// Each key implies all keys listed in its array (transitive dependencies)
+const OBJECT_DEPENDENCY_CHAIN = [
+    'modifyAllRecords',
+    'viewAllRecords',
+    'allowDelete',
+    'allowEdit',
+    'allowRead',
+];
+export function resolveObjectDependencies(perms) {
+    const resolved = { ...perms };
+    const autoEnabled = [];
+    // Find the highest permission that's enabled, then enable everything below it
+    let highestIndex = -1;
+    for (let i = 0; i < OBJECT_DEPENDENCY_CHAIN.length; i++) {
+        if (resolved[OBJECT_DEPENDENCY_CHAIN[i]]) {
+            highestIndex = i;
+            break;
+        }
+    }
+    if (highestIndex >= 0) {
+        for (let i = highestIndex + 1; i < OBJECT_DEPENDENCY_CHAIN.length; i++) {
+            const key = OBJECT_DEPENDENCY_CHAIN[i];
+            if (!resolved[key]) {
+                resolved[key] = true;
+                autoEnabled.push(key);
+            }
+        }
+    }
+    // Also handle Edit → Read independently (Edit without Delete should still imply Read)
+    if (resolved.allowEdit && !resolved.allowRead) {
+        resolved.allowRead = true;
+        if (!autoEnabled.includes('allowRead'))
+            autoEnabled.push('allowRead');
+    }
+    if (resolved.allowCreate && !resolved.allowRead) {
+        resolved.allowRead = true;
+        if (!autoEnabled.includes('allowRead'))
+            autoEnabled.push('allowRead');
+    }
+    return { resolved, autoEnabled };
+}
+export function resolveFieldDependencies(perms) {
+    const resolved = { ...perms };
+    const autoEnabled = [];
+    if (resolved.editable && !resolved.readable) {
+        resolved.readable = true;
+        autoEnabled.push('readable');
+    }
+    return { resolved, autoEnabled };
+}
+//# sourceMappingURL=dependencies.js.map

package/dist/dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../src/dependencies.ts"],"names":[],"mappings":"AAEA,0EAA0E;AAC1E,MAAM,uBAAuB,GAA0B;IACrD,kBAAkB;IAClB,gBAAgB;IAChB,aAAa;IACb,WAAW;IACX,WAAW;CACZ,CAAC;AAEF,MAAM,UAAU,yBAAyB,CAAC,KAAwB;IAIhE,MAAM,QAAQ,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;IAC9B,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,8EAA8E;IAC9E,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,uBAAuB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxD,IAAI,QAAQ,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,YAAY,GAAG,CAAC,CAAC;YACjB,MAAM;QACR,CAAC;IACH,CAAC;IAED,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;QACtB,KAAK,IAAI,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC,GAAG,uBAAuB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvE,MAAM,GAAG,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC;YACvC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnB,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;gBACrB,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC;IAED,sFAAsF;IACtF,IAAI,QAAQ,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC9C,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,QAAQ,CAAC,WAAW,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;QAChD,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACxE,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAuB;IAI9D,MAAM,QAAQ,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;IAC9B,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,IAAI,QAAQ,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAC5C,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC;QACzB,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACnC,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,10 @@
+import type { OrgInfo, SfdxProject } from './types.js';
+export declare function findProjectRoot(startDir?: string): string;
+export declare function readSfdxProject(projectRoot: string): SfdxProject;
+export declare function getPackageDirectories(project: SfdxProject, projectRoot: string): string[];
+export declare function getAuthenticatedOrg(): OrgInfo;
+export declare function validateEnvironment(): {
+    projectRoot: string;
+    project: SfdxProject;
+    org: OrgInfo;
+};

package/dist/env.js

@@ -0,0 +1,54 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+export function findProjectRoot(startDir = process.cwd()) {
+    let dir = startDir;
+    while (true) {
+        if (existsSync(resolve(dir, 'sfdx-project.json'))) {
+            return dir;
+        }
+        const parent = resolve(dir, '..');
+        if (parent === dir) {
+            throw new Error('Not inside a Salesforce DX project. No sfdx-project.json found.\n' +
+                'Run this command from within an SFDX project directory.');
+        }
+        dir = parent;
+    }
+}
+export function readSfdxProject(projectRoot) {
+    const filePath = resolve(projectRoot, 'sfdx-project.json');
+    const content = readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+}
+export function getPackageDirectories(project, projectRoot) {
+    return project.packageDirectories.map((d) => resolve(projectRoot, d.path));
+}
+export function getAuthenticatedOrg() {
+    try {
+        const result = execSync('sf org display --json', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const parsed = JSON.parse(result);
+        if (parsed.status !== 0) {
+            throw new Error(parsed.message || 'Failed to get org info');
+        }
+        const { username, id: orgId, instanceUrl } = parsed.result;
+        return { username, orgId, instanceUrl };
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes('No default org found')) {
+            throw new Error('No authenticated Salesforce org found.\n' +
+                'Run `sf org login web` or `sf config set target-org <alias>` first.');
+        }
+        throw new Error('Failed to connect to Salesforce org. Ensure `sf` CLI is installed and you have an authenticated org.\n' +
+            `Details: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function validateEnvironment() {
+    const projectRoot = findProjectRoot();
+    const project = readSfdxProject(projectRoot);
+    const org = getAuthenticatedOrg();
+    return { projectRoot, project, org };
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,MAAM,UAAU,eAAe,CAAC,WAAmB,OAAO,CAAC,GAAG,EAAE;IAC9D,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC;YAClD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,mEAAmE;gBACjE,yDAAyD,CAC5D,CAAC;QACJ,CAAC;QACD,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAoB,EAAE,WAAmB;IAC7E,OAAO,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,uBAAuB,EAAE;YAC/C,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,IAAI,wBAAwB,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;QAC3D,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC;YACzE,MAAM,IAAI,KAAK,CACb,0CAA0C;gBACxC,qEAAqE,CACxE,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CACb,wGAAwG;YACtG,YAAY,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACjE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC;IACtC,MAAM,OAAO,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;IAClC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;AACvC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};