@scriptables/manifest/README.md

Utilities to generate, parse, and update manifest headers in Scriptable scripts.

# @scriptables/manifest

Utilities to generate, parse, and update manifest headers in [Scriptable](https://scriptable.app) scripts.

## Overview

[Scriptable](https://scriptable.app) scripts can include special manifest comments at the top of the file that configure
various script behaviors and appearance settings. This library makes it easy to work with these manifests
programmatically.

Example manifest:

```js
// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: blue; icon-glyph: circle; always-run-in-app: true; share-sheet-inputs: file-url, url;
```

## Installation

```bash
npm install @scriptables/manifest

# or
yarn add @scriptables/manifest

# or
pnpm add @scriptables/manifest

# or
bun add @scriptables/manifest
```

## Quick Start

```typescript
import {generateScriptableBanner, parseScriptableManifest, mergeScriptableBanner} from '@scriptables/manifest';

// Generate a new manifest banner
const manifest = {
  name: 'my-widget',
  iconColor: 'blue',
  iconGlyph: 'star',
  alwaysRunInApp: true,
};

const banner = generateScriptableBanner(manifest);

// Parse an existing script's manifest
const script = `// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: red;

console.log('Hello world');`;

const {manifest: parsedManifest, content} = parseScriptableManifest(script);
console.log(parsedManifest); // { iconColor: 'red' }

// Update an existing script's manifest
const {banner: newBanner, content: updatedScript} = mergeScriptableBanner(script, {
  iconColor: 'blue',
  iconGlyph: 'star',
});
```

## API Reference

### Core Functions

#### `generateScriptableBanner()`

Generates a new manifest banner.

```typescript
function generateScriptableBanner(manifest?: ScriptableManifest, noDefaults = false): string;
```

Example:

```typescript
const banner = generateScriptableBanner({
  iconColor: 'red',
  iconGlyph: 'star',
});
```

#### `parseScriptableManifest()`

Parses a script to extract its manifest settings and content.

```typescript
function parseScriptableManifest(script: string): {
  manifest: Partial<ScriptableManifest> | null;
  rawHeader: string;
  content: string;
};
```

Example:

```typescript
const {manifest, content} = parseScriptableManifest(script);
console.log(manifest.iconColor); // 'red'
```

#### `mergeScriptableBanner()`

Updates a script's manifest with new settings.

```typescript
function mergeScriptableBanner(
  script: string,
  manifestOrOldScript?: Partial<ScriptableManifest> | string,
): {
  banner: string;
  content: string;
};
```

Example:

```typescript
const {banner, content} = mergeScriptableBanner(script, {
  iconColor: 'blue',
  iconGlyph: 'star',
});
```

### Helper Functions

- `hasBannerManifest(script: string)`: Checks if a script has a manifest banner
- `isStaticBanner(line: string)`: Checks if a line is part of the static banner
- `isManifestBanner(line: string)`: Checks if a line contains manifest settings
- `isScriptableBanner(line: string)`: Checks if a line is part of any banner type
- `normalizeManifest(manifest: object)`: Normalizes manifest keys to camelCase format

## Types

```typescript
interface ScriptableManifest {
  name?: string;
  alwaysRunInApp?: boolean;
  shareSheetInputs?: ScriptableShareSheetInputs;
  iconColor?: string;
  iconGlyph?: string;
}

type ScriptableShareSheetInputs = Array<'file-url' | 'url' | 'plain-text' | 'images'>;
```

## Advanced Usage

### Working with Share Sheet Inputs

```typescript
const manifest = {
  name: 'file-processor',
  shareSheetInputs: ['file-url', 'images'],
  alwaysRunInApp: true,
};

const banner = generateScriptableBanner(manifest);
```

### Handling Different Key Formats

The library supports different key formats for manifest properties:

```typescript
// All these are equivalent
const manifest1 = {iconColor: 'red'};
const manifest2 = {'icon-color': 'red'};
const manifest3 = {icon_color: 'red'};
```

## Error Handling

The library throws errors in these cases:

- Invalid manifest format
- Missing required properties
- Invalid share sheet input types

Example with error handling:

```typescript
try {
  const {banner, content} = mergeScriptableBanner(script, {
    shareSheetInputs: ['invalid-type'], // This will throw an error
  });
} catch (error) {
  console.error('Failed to merge manifest:', error);
}
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Credits

This project draws inspiration from [rollup-plugin-scriptable](https://github.com/jag-k/rollup-plugin-scriptable).

## License

Apache-2.0