feat: add JSON and Markdown output support for manifest commands

Implement comprehensive JSON/Markdown output for all manifest generation
commands and wrapper configuration, enabling programmatic consumption and
documentation generation.

**New Output Helper:**
- output-manifest.mts: Central helper for manifest generation results
  - Supports JSON, Markdown, and text output modes
  - Structured data includes files generated, type (gradle/sbt), success status
  - Markdown output includes next steps guidance

**Gradle/Kotlin Commands:**
- convert-gradle-to-maven.mts: Return CResult<ManifestResult>
  - Accept outputKind parameter (text/json/markdown)
  - Silent operation in JSON/MD modes (no spinner/logger)
  - Capture generated file paths from gradle output
- cmd-manifest-gradle.mts: Integrate outputManifest for JSON/MD
- cmd-manifest-kotlin.mts: Same integration pattern

**SBT/Scala Commands:**
- convert-sbt-to-maven.mts: Return CResult<ManifestResult>
  - Accept outputKind parameter
  - Silent operation in JSON/MD modes
  - Handle stderr as string or Buffer correctly
- cmd-manifest-scala.mts: Integrate outputManifest for JSON/MD

**Auto-detect Command:**
- generate_auto_manifest.mts: Pass outputKind to all converters
  - Conditionally show text mode logging
  - Each generator handles its own output format
- cmd-manifest-auto.mts: Already passes outputKind through

**Wrapper Command:**
- cmd-wrapper.mts: Track modified/skipped shell config files
  - JSON output: action, modifiedFiles, skippedFiles, success status
  - Markdown output: formatted report with file lists and status
  - Text mode preserves existing behavior

**Architecture:**
- Manifest generators now return CResult for error handling
- Text mode output remains in converters (backward compatible)
- JSON/MD modes delegate to output helpers
- Consistent pattern across all manifest commands

All existing text output behavior preserved. JSON/MD output is opt-in via
--json or --markdown flags.

Author: jdalton

packages/cli/src/commands/manifest/cmd-manifest-auto.mts

@@ -68,7 +68,7 @@ async function run(
     importMeta,
     parentName,
   })
-  // TODO: Implement json/md further.
+  // Feature request: Pass outputKind to manifest generators for json/md output support.
   const { json, markdown, verbose: verboseFlag } = cli.flags
 
   const dryRun = !!cli.flags['dryRun']

packages/cli/src/commands/manifest/cmd-manifest-gradle.mts

@@ -4,6 +4,7 @@ import { debug } from '@socketsecurity/lib/debug'
 import { logger } from '@socketsecurity/lib/logger'
 
 import { convertGradleToMaven } from './convert-gradle-to-maven.mts'
+import { outputManifest } from './output-manifest.mts'
 import { DRY_RUN_BAILING_NOW } from '../../constants/cli.mjs'
 import { REQUIREMENTS_TXT } from '../../constants/paths.mjs'
 import { SOCKET_JSON } from '../../constants/socket.mts'
@@ -96,7 +97,7 @@ async function run(
 
   const dryRun = !!cli.flags['dryRun']
 
-  // TODO: Implement json/md further.
+  // Feature request: Pass outputKind to convertGradleToMaven for json/md output support.
   const outputKind = getOutputKind(json, markdown)
 
   let [cwd = '.'] = cli.input
@@ -153,9 +154,9 @@ async function run(
     logger.groupEnd()
   }
 
-  // TODO: We're not sure it's feasible to parse source file from stdin. We could
-  //       try, store contents in a file in some folder, target that folder... what
-  //       would the file name be?
+  // Note: stdin input not supported. Gradle manifest generation requires a directory
+  // context with build files (build.gradle, settings.gradle, etc.) that can't be
+  // meaningfully provided via stdin.
 
   const wasValidInput = checkCommandInput(outputKind, {
     nook: true,
@@ -179,13 +180,20 @@ async function run(
     return
   }
 
-  await convertGradleToMaven({
+  const result = await convertGradleToMaven({
     bin: String(bin),
     cwd,
     gradleOpts: String(gradleOpts || '')
       .split(' ')
       .map(s => s.trim())
       .filter(Boolean),
+    outputKind,
     verbose: Boolean(verbose),
   })
+
+  // In text mode, output is already handled by convertGradleToMaven.
+  // For json/markdown modes, we need to call the output helper.
+  if (outputKind !== 'text') {
+    await outputManifest(result, outputKind, '-')
+  }
 }

packages/cli/src/commands/manifest/cmd-manifest-kotlin.mts

@@ -4,6 +4,7 @@ import { debug } from '@socketsecurity/lib/debug'
 import { logger } from '@socketsecurity/lib/logger'
 
 import { convertGradleToMaven } from './convert-gradle-to-maven.mts'
+import { outputManifest } from './output-manifest.mts'
 import { DRY_RUN_BAILING_NOW } from '../../constants/cli.mjs'
 import { REQUIREMENTS_TXT } from '../../constants/paths.mjs'
 import { SOCKET_JSON } from '../../constants/socket.mts'
@@ -19,11 +20,11 @@ import type {
   CliCommandContext,
 } from '../../utils/cli/with-subcommands.mjs'
 
-// TODO: We may want to dedupe some pieces for all gradle languages. I think it
-//       makes sense to have separate commands for them and I think it makes
-//       sense for the help panels to note the requested language, rather than
-//       `socket manifest kotlin` to print help screens with `gradle` as the
-//       command. Room for improvement.
+// Design note: Gradle language commands (gradle, kotlin, scala) share similar code
+// but maintain separate commands for clarity. This allows language-specific help text
+// and clearer user experience (e.g., "socket manifest kotlin" shows Kotlin-specific
+// help rather than generic gradle help). Future refactoring could extract shared logic
+// while preserving separate command interfaces.
 const config: CliCommandConfig = {
   commandName: 'kotlin',
   description:
@@ -101,7 +102,7 @@ async function run(
 
   const dryRun = !!cli.flags['dryRun']
 
-  // TODO: Implement json/md further.
+  // Feature request: Pass outputKind to convertGradleToMaven for json/md output support.
   const outputKind = getOutputKind(json, markdown)
 
   let [cwd = '.'] = cli.input
@@ -158,9 +159,9 @@ async function run(
     logger.groupEnd()
   }
 
-  // TODO: We're not sure it's feasible to parse source file from stdin. We could
-  //       try, store contents in a file in some folder, target that folder... what
-  //       would the file name be?
+  // Note: stdin input not supported. Gradle manifest generation requires a directory
+  // context with build files (build.gradle.kts, settings.gradle.kts, etc.) that can't be
+  // meaningfully provided via stdin.
 
   const wasValidInput = checkCommandInput(outputKind, {
     nook: true,
@@ -184,13 +185,20 @@ async function run(
     return
   }
 
-  await convertGradleToMaven({
+  const result = await convertGradleToMaven({
     bin: String(bin),
     cwd,
     gradleOpts: String(gradleOpts || '')
       .split(' ')
       .map(s => s.trim())
       .filter(Boolean),
+    outputKind,
     verbose: Boolean(verbose),
   })
+
+  // In text mode, output is already handled by convertGradleToMaven.
+  // For json/markdown modes, we need to call the output helper.
+  if (outputKind !== 'text') {
+    await outputManifest(result, outputKind, '-')
+  }
 }

packages/cli/src/commands/manifest/cmd-manifest-scala.mts

@@ -4,6 +4,7 @@ import { debug } from '@socketsecurity/lib/debug'
 import { logger } from '@socketsecurity/lib/logger'
 
 import { convertSbtToMaven } from './convert-sbt-to-maven.mts'
+import { outputManifest } from './output-manifest.mts'
 import { DRY_RUN_BAILING_NOW } from '../../constants/cli.mjs'
 import { REQUIREMENTS_TXT } from '../../constants/paths.mjs'
 import { SOCKET_JSON } from '../../constants/socket.mts'
@@ -114,7 +115,7 @@ async function run(
   // If given path is absolute then cwd should not affect it.
   cwd = path.resolve(process.cwd(), cwd)
 
-  // TODO: Implement json/md further.
+  // Feature request: Pass outputKind to convertSbtToMaven for json/md output support.
   const outputKind = getOutputKind(json, markdown)
 
   const sockJson = readOrDefaultSocketJson(cwd)
@@ -181,9 +182,9 @@ async function run(
     logger.groupEnd()
   }
 
-  // TODO: We're not sure it's feasible to parse source file from stdin. We could
-  //       try, store contents in a file in some folder, target that folder... what
-  //       would the file name be?
+  // Note: stdin input not supported. SBT manifest generation requires a directory
+  // context with build files (build.sbt, project/, etc.) that can't be meaningfully
+  // provided via stdin.
 
   const wasValidInput = checkCommandInput(outputKind, {
     nook: true,
@@ -208,14 +209,21 @@ async function run(
     return
   }
 
-  await convertSbtToMaven({
+  const result = await convertSbtToMaven({
     bin: String(bin),
     cwd: cwd,
     out: String(out),
+    outputKind,
     sbtOpts: String(sbtOpts)
       .split(' ')
       .map(s => s.trim())
       .filter(Boolean),
     verbose: Boolean(verbose),
   })
+
+  // In text mode, output is already handled by convertSbtToMaven.
+  // For json/markdown modes, we need to call the output helper.
+  if (outputKind !== 'text') {
+    await outputManifest(result, outputKind, String(out))
+  }
 }

packages/cli/src/commands/manifest/convert-gradle-to-maven.mts

@@ -7,39 +7,49 @@ import { spawn } from '@socketsecurity/lib/spawn'
 
 import { distPath } from '../../constants/paths.mjs'
 
+import type { CResult, OutputKind } from '../../types.mts'
+import type { ManifestResult } from './output-manifest.mts'
+
 export async function convertGradleToMaven({
   bin,
   cwd,
   gradleOpts,
+  outputKind = 'text',
   verbose,
 }: {
   bin: string
   cwd: string
-  verbose: boolean
   gradleOpts: string[]
-}) {
-  // TODO: Implement json/md.
+  outputKind?: OutputKind | undefined
+  verbose: boolean
+}): Promise<CResult<ManifestResult>> {
 
-  // Note: use resolve because the bin could be an absolute path, away from cwd
-  // TODO: what about $PATH resolved commands? (`gradlew` without dir prefix)
+  // Note: Resolve bin relative to cwd (or use absolute path if provided).
+  // We don't resolve against $PATH since gradlew is typically a local wrapper script.
+  // Users can provide absolute paths if they need to reference system-wide installations.
   const rBin = path.resolve(cwd, bin)
   const binExists = fs.existsSync(rBin)
   const cwdExists = fs.existsSync(cwd)
 
-  logger.group('gradle2maven:')
-  logger.info(`- executing: \`${rBin}\``)
-  if (!binExists) {
-    logger.warn(
-      'Warning: It appears the executable could not be found. An error might be printed later because of that.',
-    )
-  }
-  logger.info(`- src dir: \`${cwd}\``)
-  if (!cwdExists) {
-    logger.warn(
-      'Warning: It appears the src dir could not be found. An error might be printed later because of that.',
-    )
+  // Only show logging in text mode.
+  const isTextMode = outputKind === 'text'
+
+  if (isTextMode) {
+    logger.group('gradle2maven:')
+    logger.info(`- executing: \`${rBin}\``)
+    if (!binExists) {
+      logger.warn(
+        'Warning: It appears the executable could not be found. An error might be printed later because of that.',
+      )
+    }
+    logger.info(`- src dir: \`${cwd}\``)
+    if (!cwdExists) {
+      logger.warn(
+        'Warning: It appears the src dir could not be found. An error might be printed later because of that.',
+      )
+    }
+    logger.groupEnd()
   }
-  logger.groupEnd()
 
   try {
     // Run gradlew with the init script we provide which should yield zero or more
@@ -50,50 +60,92 @@ export async function convertGradleToMaven({
     // Note: init.gradle will be exported by .config/rollup.cli-js.config.mjs
     const initLocation = path.join(distPath, 'init.gradle')
     const commandArgs = ['--init-script', initLocation, ...gradleOpts, 'pom']
-    if (verbose) {
+    if (verbose && isTextMode) {
       logger.log('[VERBOSE] Executing:', [bin], ', args:', commandArgs)
     }
-    logger.log(`Converting gradle to maven from \`${bin}\` on \`${cwd}\` ...`)
-    const output = await execGradleWithSpinner(rBin, commandArgs, cwd)
-    if (verbose) {
+    if (isTextMode) {
+      logger.log(`Converting gradle to maven from \`${bin}\` on \`${cwd}\` ...`)
+    }
+    const output = await execGradleWithSpinner(
+      rBin,
+      commandArgs,
+      cwd,
+      isTextMode,
+    )
+    if (verbose && isTextMode) {
       logger.group('[VERBOSE] gradle stdout:')
       logger.log(output)
       logger.groupEnd()
     }
     if (output.code) {
-      process.exitCode = 1
-      logger.fail(`Gradle exited with exit code ${output.code}`)
-      // (In verbose mode, stderr was printed above, no need to repeat it)
-      if (!verbose) {
-        logger.group('stderr:')
-        logger.error(output.stderr)
-        logger.groupEnd()
+      if (isTextMode) {
+        process.exitCode = 1
+        logger.fail(`Gradle exited with exit code ${output.code}`)
+        // (In verbose mode, stderr was printed above, no need to repeat it)
+        if (!verbose) {
+          logger.group('stderr:')
+          logger.error(output.stderr)
+          logger.groupEnd()
+        }
+      }
+      return {
+        ok: false,
+        code: output.code,
+        message: `Gradle exited with exit code ${output.code}`,
+        cause: output.stderr,
       }
-      return
     }
-    logger.success('Executed gradle successfully')
-    logger.log('Reported exports:')
+
+    // Extract file paths from output.
+    const files: string[] = []
     output.stdout.replace(
       /^POM file copied to: (.*)/gm,
       (_all: string, fn: string) => {
-        logger.log('- ', fn)
+        files.push(fn)
+        if (isTextMode) {
+          logger.log('- ', fn)
+        }
         return fn
       },
     )
-    logger.log('')
-    logger.log(
-      'Next step is to generate a Scan by running the `socket scan create` command on the same directory',
-    )
+
+    if (isTextMode) {
+      logger.success('Executed gradle successfully')
+      logger.log('Reported exports:')
+      files.forEach(fn => logger.log('- ', fn))
+      logger.log('')
+      logger.log(
+        'Next step is to generate a Scan by running the `socket scan create` command on the same directory',
+      )
+    }
+
+    return {
+      ok: true,
+      data: {
+        files,
+        type: 'gradle',
+        success: true,
+      },
+    }
   } catch (e) {
-    process.exitCode = 1
-    logger.fail(
+    const errorMessage =
       'There was an unexpected error while generating manifests' +
-        (verbose ? '' : '  (use --verbose for details)'),
-    )
-    if (verbose) {
-      logger.group('[VERBOSE] error:')
-      logger.log(e)
-      logger.groupEnd()
+      (verbose ? '' : '  (use --verbose for details)')
+
+    if (isTextMode) {
+      process.exitCode = 1
+      logger.fail(errorMessage)
+      if (verbose) {
+        logger.group('[VERBOSE] error:')
+        logger.log(e)
+        logger.groupEnd()
+      }
+    }
+
+    return {
+      ok: false,
+      message: errorMessage,
+      cause: e instanceof Error ? e.message : String(e),
     }
   }
 }
@@ -102,17 +154,20 @@ async function execGradleWithSpinner(
   bin: string,
   commandArgs: string[],
   cwd: string,
+  showSpinner: boolean,
 ): Promise<{ code: number; stdout: string; stderr: string }> {
   let pass = false
-  const spinner = getSpinner()
+  const spinner = showSpinner ? getSpinner() : undefined
   try {
-    logger.info(
-      '(Running gradle can take a while, it depends on how long gradlew has to run)',
-    )
-    logger.info(
-      '(It will show no output, you can use --verbose to see its output)',
-    )
-    spinner?.start('Running gradlew...')
+    if (showSpinner) {
+      logger.info(
+        '(Running gradle can take a while, it depends on how long gradlew has to run)',
+      )
+      logger.info(
+        '(It will show no output, you can use --verbose to see its output)',
+      )
+      spinner?.start('Running gradlew...')
+    }
 
     const output = await spawn(bin, commandArgs, {
       // We can pipe the output through to have the user see the result