Add programmatic API and update to v1.0.0 (#19)

* Add programmatic API and update to v1.0.0

- Add runPatch() function for programmatic usage from socket-cli
- Add ./run export in package.json for subpath import
- Update postinstall detection to use socket CLI subcommand format
- Change generated postinstall from npx @socketsecurity/socket-patch to socket patch apply
- Add debug logging support via SOCKET_PATCH_DEBUG env var
- Bump version to 1.0.0 for first stable release

* Exit successfully when no .socket folder exists

The apply command now exits with code 0 when no manifest is found,
treating it as a successful no-op. This allows postinstall scripts
to run without failing when no patches are configured.

Author: mikolalysenko

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/socket-patch",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "packageManager": "[email protected]",
   "description": "CLI tool for applying security patches to dependencies",
   "main": "dist/index.js",
@@ -48,6 +48,11 @@
       "types": "./dist/package-json/index.d.ts",
       "require": "./dist/package-json/index.js",
       "import": "./dist/package-json/index.js"
+    },
+    "./run": {
+      "types": "./dist/run.d.ts",
+      "require": "./dist/run.js",
+      "import": "./dist/run.js"
     }
   },
   "scripts": {

src/commands/apply.ts

@@ -228,14 +228,15 @@ export const applyCommand: CommandModule<{}, ApplyArgs> = {
         ? argv['manifest-path']
         : path.join(argv.cwd, argv['manifest-path'])
 
-      // Check if manifest exists
+      // Check if manifest exists - exit successfully if no .socket folder is set up
       try {
         await fs.access(manifestPath)
       } catch {
+        // No manifest means no patches to apply - this is a successful no-op
         if (!argv.silent) {
-          console.error(`Manifest not found at ${manifestPath}`)
+          console.log('No .socket folder found, skipping patch application.')
         }
-        process.exit(1)
+        process.exit(0)
       }
 
       const { success, results } = await applyPatches(

src/index.ts

@@ -15,3 +15,7 @@ export * from './manifest/recovery.js'
 
 // Re-export constants
 export * from './constants.js'
+
+// Re-export programmatic API
+export { runPatch } from './run.js'
+export type { PatchOptions } from './run.js'

src/package-json/detect.test.ts

@@ -313,6 +313,40 @@ describe('isPostinstallConfigured', () => {
       assert.equal(result.configured, true)
       assert.equal(result.needsUpdate, false)
     })
+
+    it('should detect socket patch apply (Socket CLI subcommand) as configured', () => {
+      const packageJson = {
+        name: 'test',
+        version: '1.0.0',
+        scripts: {
+          postinstall: 'socket patch apply',
+        },
+      }
+
+      const result = isPostinstallConfigured(packageJson)
+
+      assert.equal(
+        result.configured,
+        true,
+        'socket patch apply (CLI subcommand) should be recognized',
+      )
+      assert.equal(result.needsUpdate, false)
+    })
+
+    it('should detect socket patch apply with --silent flag as configured', () => {
+      const packageJson = {
+        name: 'test',
+        version: '1.0.0',
+        scripts: {
+          postinstall: 'socket patch apply --silent',
+        },
+      }
+
+      const result = isPostinstallConfigured(packageJson)
+
+      assert.equal(result.configured, true)
+      assert.equal(result.needsUpdate, false)
+    })
   })
 
   describe('Edge Case 5: Invalid or malformed data', () => {
@@ -377,19 +411,19 @@ describe('isPostinstallConfigured', () => {
 describe('generateUpdatedPostinstall', () => {
   it('should create command for empty string', () => {
     const result = generateUpdatedPostinstall('')
-    assert.equal(result, 'npx @socketsecurity/socket-patch apply')
+    assert.equal(result, 'socket patch apply --silent')
   })
 
   it('should create command for whitespace-only string', () => {
     const result = generateUpdatedPostinstall('   \n\t  ')
-    assert.equal(result, 'npx @socketsecurity/socket-patch apply')
+    assert.equal(result, 'socket patch apply --silent')
   })
 
   it('should prepend to existing script', () => {
     const result = generateUpdatedPostinstall('echo "Hello"')
     assert.equal(
       result,
-      'npx @socketsecurity/socket-patch apply && echo "Hello"',
+      'socket patch apply --silent && echo "Hello"',
     )
   })
 
@@ -405,13 +439,25 @@ describe('generateUpdatedPostinstall', () => {
     assert.equal(result, existing)
   })
 
-  it('should prepend to script with socket apply (main CLI)', () => {
+  it('should preserve socket patch apply (CLI subcommand)', () => {
+    const existing = 'socket patch apply'
+    const result = generateUpdatedPostinstall(existing)
+    assert.equal(result, existing)
+  })
+
+  it('should preserve socket patch apply --silent', () => {
+    const existing = 'socket patch apply --silent'
+    const result = generateUpdatedPostinstall(existing)
+    assert.equal(result, existing)
+  })
+
+  it('should prepend to script with socket apply (non-patch command)', () => {
     const existing = 'socket apply'
     const result = generateUpdatedPostinstall(existing)
     assert.equal(
       result,
-      'npx @socketsecurity/socket-patch apply && socket apply',
-      'Should add socket-patch even if socket apply is present',
+      'socket patch apply --silent && socket apply',
+      'Should add socket patch apply even if socket apply is present',
     )
   })
 })
@@ -430,7 +476,7 @@ describe('updatePackageJsonContent', () => {
     assert.ok(updated.scripts)
     assert.equal(
       updated.scripts.postinstall,
-      'npx @socketsecurity/socket-patch apply',
+      'socket patch apply --silent',
     )
   })
 
@@ -450,7 +496,7 @@ describe('updatePackageJsonContent', () => {
     const updated = JSON.parse(result.content)
     assert.equal(
       updated.scripts.postinstall,
-      'npx @socketsecurity/socket-patch apply',
+      'socket patch apply --silent',
     )
     assert.equal(updated.scripts.test, 'jest', 'Should preserve other scripts')
     assert.equal(updated.scripts.build, 'tsc', 'Should preserve other scripts')
@@ -471,11 +517,11 @@ describe('updatePackageJsonContent', () => {
     assert.equal(result.oldScript, 'echo "Setup complete"')
     assert.equal(
       result.newScript,
-      'npx @socketsecurity/socket-patch apply && echo "Setup complete"',
+      'socket patch apply --silent && echo "Setup complete"',
     )
   })
 
-  it('should not modify when already configured', () => {
+  it('should not modify when already configured with legacy format', () => {
     const content = JSON.stringify({
       name: 'test',
       version: '1.0.0',
@@ -490,6 +536,21 @@ describe('updatePackageJsonContent', () => {
     assert.equal(result.content, content)
   })
 
+  it('should not modify when already configured with socket patch apply', () => {
+    const content = JSON.stringify({
+      name: 'test',
+      version: '1.0.0',
+      scripts: {
+        postinstall: 'socket patch apply --silent',
+      },
+    })
+
+    const result = updatePackageJsonContent(content)
+
+    assert.equal(result.modified, false)
+    assert.equal(result.content, content)
+  })
+
   it('should throw error for invalid JSON', () => {
     const content = '{ invalid json }'
 
@@ -514,7 +575,7 @@ describe('updatePackageJsonContent', () => {
     const updated = JSON.parse(result.content)
     assert.equal(
       updated.scripts.postinstall,
-      'npx @socketsecurity/socket-patch apply',
+      'socket patch apply --silent',
     )
   })
 
@@ -533,7 +594,7 @@ describe('updatePackageJsonContent', () => {
     const updated = JSON.parse(result.content)
     assert.equal(
       updated.scripts.postinstall,
-      'npx @socketsecurity/socket-patch apply',
+      'socket patch apply --silent',
     )
   })
 

src/package-json/detect.ts

@@ -1,9 +1,17 @@
 /**
- * Shared logic for detecting and generating postinstall scripts
- * Used by both CLI and GitHub bot
+ * Shared logic for detecting and generating postinstall scripts.
+ * Used by both CLI and GitHub bot.
  */
 
-const SOCKET_PATCH_COMMAND = 'npx @socketsecurity/socket-patch apply'
+// The command to run for applying patches via socket CLI.
+const SOCKET_PATCH_COMMAND = 'socket patch apply --silent'
+
+// Legacy command patterns to detect existing configurations.
+const LEGACY_PATCH_PATTERNS = [
+  'socket-patch apply',
+  'npx @socketsecurity/socket-patch apply',
+  'socket patch apply',
+]
 
 export interface PostinstallStatus {
   configured: boolean
@@ -34,11 +42,13 @@ export function isPostinstallConfigured(
   }
 
   const rawPostinstall = packageJson.scripts?.postinstall
-  // Handle non-string values (null, object, array) by treating as empty string
+  // Handle non-string values (null, object, array) by treating as empty string.
   const currentScript = typeof rawPostinstall === 'string' ? rawPostinstall : ''
 
-  // Check if socket-patch apply is already present
-  const configured = currentScript.includes('socket-patch apply')
+  // Check if any socket-patch apply variant is already present.
+  const configured = LEGACY_PATCH_PATTERNS.some(pattern =>
+    currentScript.includes(pattern),
+  )
 
   return {
     configured,
@@ -48,25 +58,28 @@ export function isPostinstallConfigured(
 }
 
 /**
- * Generate an updated postinstall script that includes socket-patch
+ * Generate an updated postinstall script that includes socket-patch.
  */
 export function generateUpdatedPostinstall(
   currentPostinstall: string,
 ): string {
   const trimmed = currentPostinstall.trim()
 
-  // If empty, just add the socket-patch command
+  // If empty, just add the socket-patch command.
   if (!trimmed) {
     return SOCKET_PATCH_COMMAND
   }
 
-  // If socket-patch is already present, return unchanged
-  if (trimmed.includes('socket-patch apply')) {
+  // If any socket-patch variant is already present, return unchanged.
+  const alreadyConfigured = LEGACY_PATCH_PATTERNS.some(pattern =>
+    trimmed.includes(pattern),
+  )
+  if (alreadyConfigured) {
     return trimmed
   }
 
-  // Prepend socket-patch command so it runs first, then existing script
-  // Using && ensures existing script only runs if patching succeeds
+  // Prepend socket-patch command so it runs first, then existing script.
+  // Using && ensures existing script only runs if patching succeeds.
   return `${SOCKET_PATCH_COMMAND} && ${trimmed}`
 }
 

src/run.ts

@@ -0,0 +1,84 @@
+import yargs from 'yargs'
+import { applyCommand } from './commands/apply.js'
+import { getCommand } from './commands/get.js'
+import { listCommand } from './commands/list.js'
+import { removeCommand } from './commands/remove.js'
+import { rollbackCommand } from './commands/rollback.js'
+import { repairCommand } from './commands/repair.js'
+import { setupCommand } from './commands/setup.js'
+
+/**
+ * Configuration options for running socket-patch programmatically.
+ */
+export interface PatchOptions {
+  /** Socket API URL (e.g., https://api.socket.dev). */
+  apiUrl?: string
+  /** Socket API token for authentication. */
+  apiToken?: string
+  /** Organization slug. */
+  orgSlug?: string
+  /** Public patch API proxy URL. */
+  patchProxyUrl?: string
+  /** HTTP proxy URL for all requests. */
+  httpProxy?: string
+  /** Enable debug logging. */
+  debug?: boolean
+}
+
+/**
+ * Run socket-patch programmatically with provided arguments and options.
+ * Maps options to environment variables before executing yargs commands.
+ *
+ * @param args - Command line arguments to pass to yargs (e.g., ['get', 'CVE-2021-44228']).
+ * @param options - Configuration options that override environment variables.
+ * @returns Exit code (0 for success, non-zero for failure).
+ */
+export async function runPatch(
+  args: string[],
+  options?: PatchOptions
+): Promise<number> {
+  // Map options to environment variables.
+  if (options?.apiUrl) {
+    process.env.SOCKET_API_URL = options.apiUrl
+  }
+  if (options?.apiToken) {
+    process.env.SOCKET_API_TOKEN = options.apiToken
+  }
+  if (options?.orgSlug) {
+    process.env.SOCKET_ORG_SLUG = options.orgSlug
+  }
+  if (options?.patchProxyUrl) {
+    process.env.SOCKET_PATCH_PROXY_URL = options.patchProxyUrl
+  }
+  if (options?.httpProxy) {
+    process.env.SOCKET_PATCH_HTTP_PROXY = options.httpProxy
+  }
+  if (options?.debug) {
+    process.env.SOCKET_PATCH_DEBUG = '1'
+  }
+
+  try {
+    await yargs(args)
+      .scriptName('socket patch')
+      .usage('$0 <command> [options]')
+      .command(getCommand)
+      .command(applyCommand)
+      .command(rollbackCommand)
+      .command(removeCommand)
+      .command(listCommand)
+      .command(setupCommand)
+      .command(repairCommand)
+      .demandCommand(1, 'You must specify a command')
+      .help()
+      .alias('h', 'help')
+      .strict()
+      .parse()
+
+    return 0
+  } catch (error) {
+    if (process.env.SOCKET_PATCH_DEBUG) {
+      console.error('socket-patch error:', error)
+    }
+    return 1
+  }
+}