@uss-stargazer/job-queue 0.0.1 → 0.0.2

package/README.md

@@ -1,4 +1,4 @@
-# Job Queue
+# job-queue
 
 The concept is modeling your todo-list as bite-sized jobs in a First-In, First-Out (FIFO) queue.
 The goal is to increase productivity.
@@ -8,7 +8,7 @@ The goal is to increase productivity.
 
 ## Install
 
-Can be installed system-wide if you have Node/NPM installed:
+Can be installed system-wide if you have NodeJS installed:
 
 ```
 npm install --global @uss-stargazer/job-queue
@@ -22,7 +22,33 @@ job-queue --help
 jobq --help
 ```
 
-## Workflow
+## Syncing with gists
+
+`job-queue` allows you to sync data files with a gist/gists on your GitHub account. This provides 
+cloud storage and makes the program more portable.
+
+To link to a gist, provide the gist ID and a GitHub access token in config.json, like:
+
+```json
+{
+  "$schema": "/job-queue/schemas/config.schema.json",
+  "jobqueue": {
+    "local": "/job-queue/jobqueue.json",
+    "ghGistId": "00000000000000000000000000000000",
+    "ghAccessToken": "ghp_000000000000000000000000000000000000"
+  },
+  "projectpool": {
+    "local": "/job-queue/projectpool.json",
+    "ghGistId": "00000000000000000000000000000000",
+    "ghAccessToken": "ghp_000000000000000000000000000000000000"
+  },
+  "schemas": "/job-queue/schemas",
+}
+```
+
+Your gist ID can be copied easily from the URL; usually something like `https://gist.github.com/USERNAME/GIST_ID`.
+
+## Sample Workflow
 
 - _\[Daemon\]_ Spontaneous, not fleshed out ideas get immediately added to the project pool as "inactive".
 - You should generally have an idea of a few projects you want to focus on at a time. For each, push

package/dist/actions.js

@@ -170,7 +170,7 @@ const actions = {
             await projectpool.sync();
         }
         catch (error) {
-            if (error instanceof AbortError)
+            if (!(error instanceof AbortError))
                 throw error;
             console.log(chalk.red('[e]'), error.message);
             pool.push(project);

package/dist/data/config.js

@@ -3,13 +3,13 @@ import envPaths from 'env-paths';
 import path from 'path';
 import fs from 'fs/promises';
 import { existsSync } from 'fs';
-import { makeJsonData } from '../utils/jsonData.js';
 import chalk from 'chalk';
 import { JobQueueSchema, JobSchema } from './jobqueue.js';
-import { ProjectPoolSchema, ProjectSchema, } from './projectpool.js';
+import { ProjectPoolSchema, ProjectSchema } from './projectpool.js';
 import { confirm } from '@inquirer/prompts';
 import { fileURLToPath, pathToFileURL } from 'url';
 import pkg from '../../package.json' with { type: 'json' };
+import { getDataTargetNicely } from '../utils/promptUser.js';
 const jsonSchemaNames = [
     'job',
     'jobqueue',
@@ -18,12 +18,36 @@ const jsonSchemaNames = [
     'config',
 ];
 const NonemptyString = z.string().nonempty();
+const GistDataObject = z.object({
+    local: NonemptyString.meta({ title: "Local JSON path", description: "Path to local JSON file for data linked to the Gist." }),
+    ghGistId: NonemptyString.regex(/^[A-Fa-f0-9]{32}$/, { error: "Is not valid GitHub gist ID" }).meta({ title: "Gist ID", description: "ID of gist to link (can get from URL of the gist you created)." }),
+    ghAccessToken: NonemptyString.regex(/^(gh[ps]_[a-zA-Z0-9]{36}|github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59})$/, { error: "Is not valid GitHub access token" }).meta({ title: "Gist Access Token", description: "GitHub access token for read/write access to your gist." })
+}).meta({ title: "Gist-Linked JSON", description: "Data for a configuration/data file linked to a GitHub gist." });
 export const ConfigSchema = z.object({
-    jobqueue: NonemptyString.optional().meta({ title: "Jobqueue path", description: "Path to jobqueue.json." }),
-    projectpool: NonemptyString.optional().meta({ title: "Projectpool path", description: "Path to projectpool.json." }),
-    editor: NonemptyString.optional().meta({ title: "Editor command", description: "Command to run editor. Will be run like `<editor> /some/data.json` so make sure it waits." }),
+    jobqueue: z.union([
+        NonemptyString.meta({ title: "Jobqueue path", description: "Path to local jobqueue.json." }),
+        GistDataObject.meta({ title: "Gist-Linked Jobqueue", description: "Data for jobqueue.json locally and linked to gist on GitHub." })
+    ]),
+    projectpool: z.union([
+        NonemptyString.meta({ title: "Projectpool path", description: "Path to local projectpool.json." }),
+        GistDataObject.meta({ title: "Gist-Linked Jobqueue", description: "Data for projectpool.json locally and linked to gist on GitHub." })
+    ]),
     schemas: NonemptyString.meta({ title: "Schemas directory", description: `Path to directory containing: ${jsonSchemaNames.map(base => `${base}.schema.json`).join(", ")}.` }).transform((schemasDir) => Object.fromEntries(jsonSchemaNames.map((base) => [base, pathToFileURL(path.resolve(schemasDir, `${base}.schema.json`)).href]))),
+    editor: NonemptyString.optional().meta({ title: "Editor command", description: "Command to run editor. Will be run like `<editor> /some/data.json` so make sure it waits." }),
+    confirmGistUpdates: z.boolean().optional().meta({ description: "Whether to prompt before pushing or pulling a gist from GitHub." }),
+    confirmOffline: z.boolean().optional().meta({ description: "Whether to confirm before using offline (if there are gists in config)." })
 });
+export const toInputConfig = (outputData) => {
+    const schemaDir = Object.values(outputData.schemas).reduce((schemaDir, schemaPath) => {
+        const thisSchemaDir = path.dirname(fileURLToPath(schemaPath));
+        return schemaDir === null || schemaDir === thisSchemaDir
+            ? thisSchemaDir
+            : (() => {
+                throw new Error('Decoded invidual schemas are not in the same directory.');
+            })();
+    }, null);
+    return { ...outputData, schemas: schemaDir };
+};
 const jsonSchemas = {
     job: JobSchema,
     jobqueue: JobQueueSchema,
@@ -52,7 +76,9 @@ const getJsonSchemaId = (schemaFileUrl) => path.posix.join(pkg.version, path.bas
 const versionFromJsonSchemaId = (id) => path.dirname(id);
 const updateJsonSchema = async (schemaSchema, schemaFileUrl) => {
     const schemaPath = fileURLToPath(schemaFileUrl);
-    await fs.mkdir(path.dirname(schemaPath), { recursive: true });
+    const schemaDir = path.dirname(schemaPath);
+    if (!existsSync(schemaDir))
+        await fs.mkdir(schemaDir, { recursive: true });
     return await fs.writeFile(schemaPath, JSON.stringify({
         $id: getJsonSchemaId(schemaFileUrl),
         ...schemaSchema.toJSONSchema({
@@ -61,10 +87,7 @@ const updateJsonSchema = async (schemaSchema, schemaFileUrl) => {
         }),
     }, undefined, '  '));
 };
-const defaultData = {
-    jobqueue: { queue: [] },
-    projectpool: { pool: [] },
-};
+export const getDataPathFromConfig = (data) => (typeof data === 'string' ? data : data.local);
 const createConfig = async (configDir, override) => {
     const config = {
         jobqueue: path.resolve(configDir, 'jobqueue.json'),
@@ -73,39 +96,18 @@ const createConfig = async (configDir, override) => {
         ...override,
     };
     const decodedConfig = ConfigSchema.decode(config);
-    for (const key of ['jobqueue', 'projectpool']) {
-        if (!existsSync(config[key])) {
-            console.log(chalk.blue('[i]'), `Creating ${path.join('{config}', path.relative(configDir, config[key]))}...`);
-            await fs.writeFile(config[key], JSON.stringify({
-                $schema: decodedConfig.schemas[key],
-                ...defaultData[key],
-            }, undefined, '  '));
-        }
-    }
-    await fs.mkdir(config.schemas);
+    if (!existsSync(config.schemas))
+        await fs.mkdir(config.schemas);
     for (const schema of jsonSchemaNames) {
         if (!existsSync(decodedConfig.schemas[schema])) {
             console.log(chalk.blue('[i]'), `Creating ${path.join('{config}', path.relative(configDir, fileURLToPath(decodedConfig.schemas[schema])))}...`);
             await updateJsonSchema(jsonSchemas[schema], decodedConfig.schemas[schema]);
         }
     }
-    return { encoded: config, decoded: decodedConfig };
+    return { encoded: config, jsonSchemaUrl: decodedConfig.schemas.config };
 };
-const checkConfig = async (config, configPath) => {
+const checkConfigSchemas = async (config, configPath) => {
     try {
-        for (const key of ['jobqueue', 'projectpool']) {
-            if (!existsSync(config[key]))
-                if (['jobqueue', 'projectpool'].includes(key) &&
-                    (await confirm({
-                        message: `File at config.${key} does not exist. Want to create it?`,
-                    })))
-                    await fs.writeFile(config[key], JSON.stringify({
-                        $schema: config.schemas[key],
-                        ...defaultData[key],
-                    }, undefined, '  '));
-                else
-                    throw new Error(`File '${config[key]}' in config does not exist`);
-        }
         const outdatedSchemas = [];
         for (const schema of Object.keys(config.schemas)) {
             const schemaPath = fileURLToPath(config.schemas[schema]);
@@ -115,7 +117,7 @@ const checkConfig = async (config, configPath) => {
                 }));
                 const version = schemaJson.$id && versionFromJsonSchemaId(schemaJson.$id);
                 if (!version || !/^\d+\.\d+\.\d+$/.test(version)) {
-                    console.log(chalk.yellow('[w]'), `${path.join('{config}', path.basename(config.schemas[schema]))} is malformed. Overwriting...`);
+                    console.log(chalk.yellow('[w]'), `${path.join('{schemas}', path.basename(config.schemas[schema]))} is malformed. Overwriting...`);
                     await updateJsonSchema(jsonSchemas[schema], config.schemas[schema]);
                 }
                 else if (version !== pkg.version) {
@@ -123,7 +125,7 @@ const checkConfig = async (config, configPath) => {
                 }
             }
             else {
-                console.log(chalk.blue('[i]'), `${path.join('{config}', path.basename(config.schemas[schema]))} does not exist. Creating...`);
+                console.log(chalk.blue('[i]'), `${path.join('{schemas}', path.basename(config.schemas[schema]))} does not exist. Creating...`);
                 await updateJsonSchema(jsonSchemas[schema], config.schemas[schema]);
             }
         }
@@ -142,17 +144,14 @@ const checkConfig = async (config, configPath) => {
 export const getConfig = async (overrideConfigDir, overrideConfig) => {
     const configDir = overrideConfigDir ?? path.resolve(envPaths('job-queue').config);
     const configPath = path.resolve(configDir, 'config.json');
-    await fs.mkdir(configDir, { recursive: true });
-    if (!existsSync(configPath)) {
-        console.log(chalk.blue('[i]'), `Creating config at '${configPath}'...`);
-        const { encoded: config, decoded: decodedConfig } = await createConfig(configDir, overrideConfig);
-        await fs.writeFile(configPath, JSON.stringify({
-            $schema: decodedConfig.schemas['config'],
-            ...config,
-        }, undefined, '  '));
-    }
-    const configData = await makeJsonData(configPath, ConfigSchema);
-    await checkConfig(configData.data, configPath);
+    if (!existsSync(configDir))
+        await fs.mkdir(configDir, { recursive: true });
+    const { data: configData, hadToCreate } = await getDataTargetNicely(ConfigSchema, { name: 'config.json', expectedPath: configPath }, () => createConfig(configDir, overrideConfig), false, toInputConfig);
     await updateNestedObject(configData.data, ConfigSchema.partial().decode(overrideConfig));
-    return configData;
+    await checkConfigSchemas(configData.data, configPath);
+    return {
+        config: configData,
+        path: configPath,
+        hadToCreate,
+    };
 };

package/dist/data/index.js

@@ -1,9 +1,50 @@
 import { JobQueueSchema } from './jobqueue.js';
 import { ProjectPoolSchema } from './projectpool.js';
-import { ConfigSchema } from './config.js';
+import { ConfigSchema, getDataPathFromConfig, toInputConfig, } from './config.js';
+import { select } from '@inquirer/prompts';
+import { ExitPromptError } from '@inquirer/core';
+import { AbortError } from '../utils/index.js';
+import chalk from 'chalk';
+import { haveUserUpdateData } from '../utils/promptUser.js';
 export const dataNames = ['jobqueue', 'projectpool', 'config'];
 export const dataSchemas = {
     jobqueue: JobQueueSchema,
     projectpool: ProjectPoolSchema,
     config: ConfigSchema,
 };
+export async function editData(data, configPath) {
+    try {
+        const target = await select({
+            message: 'Select data to edit',
+            choices: [
+                { name: 'jobqueue.json', value: 'jobqueue' },
+                { name: 'projectpool.json', value: 'projectpool' },
+                { name: 'config.json', value: 'config' },
+            ],
+        });
+        const targetSchema = dataSchemas[target];
+        const targetPath = target === 'config'
+            ? configPath
+            : getDataPathFromConfig(data.config.data[target]);
+        await haveUserUpdateData(targetSchema, target === 'config'
+            ? toInputConfig(data[target].data)
+            : data[target].data, {
+            editor: data.config.data.editor,
+            errorHead: 'Edit data failed',
+            jsonSchemaUrl: data.config.data.schemas[target],
+            file: { type: 'abs', path: targetPath },
+        }, {
+            preparse(raw) {
+                return raw.trim().length === 0
+                    ? { errMessage: 'Cannot delete data file.' }
+                    : 'continue';
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof AbortError || error instanceof ExitPromptError)
+            console.log(chalk.red('[e]'), error.message);
+        else
+            throw error;
+    }
+}

package/dist/data/jobqueue.js

@@ -1,7 +1,7 @@
 import * as z from 'zod';
-import { makeJsonData } from '../utils/jsonData.js';
 import { checkProjectName } from './projectpool.js';
-import { haveUserUpdateData } from '../utils/index.js';
+import { makeGistData } from '../utils/gistData.js';
+import { getDataTargetNicely, handleInvalidGist, haveUserUpdateData, makeGistConflictHandler, } from '../utils/promptUser.js';
 export const JobSchema = z.object({
     name: z.string().trim().nonempty().meta({ title: 'Job name', description: 'Short name of the job (think a single commit message). Used as job identifier.' }),
     objectivies: z.array(z.string().trim().nonempty()).meta({ title: 'Job objectivies', description: 'A list of objectives to complete for this job. Purely for your benefit.' }),
@@ -11,7 +11,11 @@ export const JobSchema = z.object({
 export const JobQueueSchema = z.object({
     queue: z.array(JobSchema).meta({ title: 'Job queue' }),
 }).meta({ title: 'Job queue root', description: 'Root object for jobs/tasks FIFO queue model.' });
-export const getJobQueue = async (jsonPath) => await makeJsonData(jsonPath, JobQueueSchema);
+const defaultJobQueue = { queue: [] };
+export const getJobQueue = async (jsonPath, jsonSchemaUrl, autoCreateFiles = false, editor) => {
+    const { data } = await getDataTargetNicely(JobQueueSchema, { name: 'jobqueue.json', expectedPath: jsonPath, jsonSchemaUrl }, async () => ({ encoded: defaultJobQueue }), autoCreateFiles);
+    return await makeGistData(JobQueueSchema, data, 'jobqueue.json', makeGistConflictHandler(JobQueueSchema, editor), handleInvalidGist, "JSON to keep track of `jobqueue` data for this user's job-queue implementation (this is probably autogenerated).");
+};
 export const updateJob = async (job, projectPool, config) => {
     const pool = projectPool.data.pool;
     let userDeletedJob = false;

package/dist/data/projectpool.js

@@ -1,7 +1,7 @@
 import { confirm } from '@inquirer/prompts';
 import * as z from 'zod';
-import { makeJsonData } from '../utils/jsonData.js';
-import { haveUserUpdateData } from '../utils/index.js';
+import { makeGistData } from '../utils/gistData.js';
+import { getDataTargetNicely, handleInvalidGist, haveUserUpdateData, makeGistConflictHandler, } from '../utils/promptUser.js';
 export const ProjectSchema = z.object({
     name: z.string().trim().nonempty().meta({ title: 'Project name', description: 'Name of the project. Used as identifier.' }),
     description: z.string().optional().meta({ title: 'Project description', description: 'Longer description of the project. For your benefit, optional.' }),
@@ -11,7 +11,11 @@ export const ProjectSchema = z.object({
 export const ProjectPoolSchema = z.object({
     pool: z.array(ProjectSchema).meta({ description: 'Set of projects, works in progress or just ideas.' }),
 }).meta({ title: 'Root project pool', description: 'Root object for pool of projects.' });
-export const getProjectPool = async (jsonPath) => await makeJsonData(jsonPath, ProjectPoolSchema);
+const defaultProjectPool = { pool: [] };
+export const getProjectPool = async (jsonPath, jsonSchemaUrl, autoCreateFiles = false, editor) => {
+    const { data } = await getDataTargetNicely(ProjectPoolSchema, { name: 'projectpool.json', expectedPath: jsonPath, jsonSchemaUrl }, async () => ({ encoded: defaultProjectPool }), autoCreateFiles);
+    return await makeGistData(ProjectPoolSchema, data, 'projectpool.json', makeGistConflictHandler(ProjectPoolSchema, editor), handleInvalidGist, "JSON to keep track of `projectpool` data for this user's job-queue implementation (this is probably autogenerated).");
+};
 export const checkProjectName = (name, projects) => projects.some((project) => project.name === name);
 export const updateProject = async (project, projectPool, jobQueue, config) => {
     const pool = projectPool.data.pool;

package/dist/index.js

@@ -2,45 +2,117 @@ import chalk from 'chalk';
 import clear from 'clear';
 import figlet from 'figlet';
 import { select } from '@inquirer/prompts';
-import { ExitPromptError } from '@inquirer/core';
+import { ExitPromptError, Separator } from '@inquirer/core';
 import actions, { actionNames, actionsDependentOnJobs, actionsDependentOnProjects, } from './actions.js';
-import { getConfig } from './data/config.js';
+import { getConfig, getDataPathFromConfig } from './data/config.js';
 import { getJobQueue } from './data/jobqueue.js';
 import { getProjectPool } from './data/projectpool.js';
+import { editData } from './data/index.js';
+import { simpleDeepCompare } from './utils/index.js';
+import dns from 'dns/promises';
+import { inquirerConfirm } from './utils/promptUser.js';
+async function loadData(overrideConfigDir, overrideConfig, previousData) {
+    const { config, path: configPath, hadToCreate: autoCreateOtherFiles, } = await getConfig(overrideConfigDir, overrideConfig);
+    const data = {
+        config,
+        configPath,
+        jobqueue: await getJobQueue(getDataPathFromConfig(config.data.jobqueue), config.data.schemas.jobqueue, autoCreateOtherFiles, config.data.editor),
+        projectpool: await getProjectPool(getDataPathFromConfig(config.data.projectpool), config.data.schemas.projectpool, autoCreateOtherFiles, config.data.editor),
+    };
+    let connectionError = undefined;
+    for (const key of ['jobqueue', 'projectpool']) {
+        if (typeof config.data[key] === 'object') {
+            if (previousData &&
+                simpleDeepCompare(config.data[key], previousData.config.data[key])) {
+                if (key === 'jobqueue')
+                    data['jobqueue'] = previousData['jobqueue'];
+                else if (key === 'projectpool')
+                    data['projectpool'] = previousData['projectpool'];
+            }
+            else {
+                if (connectionError === undefined) {
+                    const resolved = await dns
+                        .resolve('github.com')
+                        .catch((error) => new Error(`Could not resolve github.com: ${error}`));
+                    connectionError = resolved instanceof Error ? resolved : null;
+                    if (connectionError)
+                        break;
+                }
+                await data[key].linkGist({
+                    id: config.data[key].ghGistId,
+                    accessToken: config.data[key].ghAccessToken,
+                });
+                if (!config.data.confirmGistUpdates ||
+                    (await inquirerConfirm(`Pull gist for ${key}?`))) {
+                    console.log(chalk.blue('[i]'), 'initial pull of gist for', key);
+                    await data[key].pull();
+                }
+            }
+        }
+    }
+    if (connectionError) {
+        console.log(chalk.red('[e]'), connectionError.message);
+        if (config.data.confirmOffline &&
+            !(await inquirerConfirm('Continue offline?')))
+            throw connectionError;
+        console.log(chalk.blue('[i]'), 'Continuing offline...');
+    }
+    return data;
+}
+async function syncData(data) {
+    for (const key of ['jobqueue', 'projectpool']) {
+        await data[key].sync();
+        if (data[key].isLinked &&
+            (!data.config.data.confirmGistUpdates ||
+                (await inquirerConfirm(`Push gist for ${key}?`)))) {
+            console.log(chalk.blue('[i]'), 'sync push of gist for', key);
+            await data[key].push();
+        }
+    }
+}
 export default async function main(overrideConfigDir, overrideConfig) {
     clear();
     console.log(chalk.yellow(figlet.textSync('JobQueue', { horizontalLayout: 'full' })));
-    const config = await getConfig(overrideConfigDir, overrideConfig);
-    const data = {
-        config: config,
-        jobqueue: await getJobQueue(config.data.jobqueue),
-        projectpool: await getProjectPool(config.data.projectpool),
-    };
+    let data = await loadData(overrideConfigDir, overrideConfig);
     console.log();
     try {
         while (true) {
             const action = await select({
                 message: 'Select action',
-                choices: actionNames.map((action) => {
-                    if (actionsDependentOnJobs.includes(action) &&
-                        data.jobqueue.data.queue.length === 0)
-                        return {
-                            name: action,
-                            value: action,
-                            disabled: '(Empty job queue)',
-                        };
-                    else if (actionsDependentOnProjects.includes(action) &&
-                        data.projectpool.data.pool.length === 0)
-                        return {
-                            name: action,
-                            value: action,
-                            disabled: '(Empty project pool)',
-                        };
-                    else
-                        return { name: action, value: action };
-                }),
+                choices: [
+                    ...actionNames.map((action) => {
+                        if (actionsDependentOnJobs.includes(action) &&
+                            data.jobqueue.data.queue.length === 0)
+                            return {
+                                name: action,
+                                value: action,
+                                disabled: '(Empty job queue)',
+                            };
+                        else if (actionsDependentOnProjects.includes(action) &&
+                            data.projectpool.data.pool.length === 0)
+                            return {
+                                name: action,
+                                value: action,
+                                disabled: '(Empty project pool)',
+                            };
+                        else
+                            return { name: action, value: action };
+                    }),
+                    new Separator(),
+                    { name: 'editData', value: 'editData' },
+                    { name: 'sync', value: 'sync' },
+                ],
+                pageSize: actionNames.length + 3,
             });
-            await actions[action](data);
+            if (action === 'editData') {
+                await editData(data, data.configPath);
+                data = await loadData(overrideConfigDir, overrideConfig, data);
+            }
+            else if (action === 'sync') {
+                await syncData(data);
+            }
+            else
+                await actions[action](data);
             console.log();
         }
     }
@@ -48,4 +120,5 @@ export default async function main(overrideConfigDir, overrideConfig) {
         if (!(error instanceof ExitPromptError))
             throw error;
     }
+    await syncData(data);
 }

package/dist/utils/gistData.js

@@ -0,0 +1,108 @@
+import * as z from 'zod';
+import { Octokit } from '@octokit/rest';
+import { simpleDeepCompare } from './index.js';
+export const isGistData = (obj) => typeof obj === 'object' &&
+    obj !== null &&
+    'isLinked' in obj &&
+    typeof obj.isLinked === 'boolean' &&
+    'pull' in obj &&
+    typeof obj.pull === 'function' &&
+    'push' in obj &&
+    typeof obj.push === 'function' &&
+    'linkGist' in obj &&
+    typeof obj.linkGist === 'function';
+export class GistDataError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+const pullGist = async (octokit, filename, gistId) => {
+    const resp = await octokit.gists.get({ gist_id: gistId });
+    if (resp.status < 200 || resp.status >= 300)
+        throw new GistDataError(`Could not pull gist for '${filename}': HTTP ${resp.status}`);
+    const gistFiles = Object.keys(resp.data.files);
+    if (!gistFiles.includes(filename))
+        throw new GistDataError(`Could not pull gist for '${filename}': '${filename}' not in gist files (${gistFiles.join(', ')})`);
+    const gistFile = resp.data.files[filename];
+    return {
+        contents: gistFile.content,
+        description: resp.data.description,
+    };
+};
+const pushGist = async (octokit, filename, gistId, gist) => {
+    if (!gist.description && !gist.contents)
+        throw new TypeError(`pushGist called with nothing to change (for '${filename}')`);
+    await octokit.gists.update({
+        gist_id: gistId,
+        description: gist.description,
+        files: {
+            [filename]: {
+                content: gist.contents,
+            },
+        },
+    });
+};
+export const makeGistData = async (schema, jsonData, filename, handleConflict, handleInvalidGist, overwriteDescription) => {
+    let octokit = null;
+    let gist = null;
+    let lastGistData = null;
+    const unlinkedPull = async () => {
+        throw new Error('Cannot pull unlinked gist');
+    };
+    const unlinkedPush = async () => {
+        throw new Error('Cannot push unlinked gist');
+    };
+    const gistData = jsonData;
+    gistData.isLinked = false;
+    gistData.pull = unlinkedPull;
+    gistData.push = unlinkedPush;
+    gistData.linkGist = async (newGistParams) => {
+        if (!newGistParams && !gistData.isLinked) {
+            return;
+        }
+        else if (!newGistParams && gistData.isLinked) {
+            gistData.pull = unlinkedPull;
+            gistData.push = unlinkedPush;
+            gistData.isLinked = false;
+        }
+        else {
+            const { id: gistId, accessToken } = newGistParams;
+            octokit = new Octokit({ auth: accessToken });
+            gistData.pull = async () => {
+                gist = await pullGist(octokit, filename, gistId);
+                if (gist.contents && gist.contents.trim().length > 0) {
+                    let parsedData;
+                    try {
+                        parsedData = schema.parse(JSON.parse(gist.contents));
+                    }
+                    catch (error) {
+                        if (!(error instanceof z.ZodError || error instanceof SyntaxError))
+                            throw error;
+                        const newData = await handleInvalidGist(gist.contents, error);
+                        if (newData !== null)
+                            gistData.data = newData;
+                    }
+                    lastGistData = parsedData;
+                    if (!simpleDeepCompare(gistData.data, parsedData))
+                        gistData.data = await handleConflict(gistData.data, parsedData);
+                    await gistData.sync();
+                }
+            };
+            gistData.push = async () => {
+                if (!gist)
+                    console.warn('pushing GistData without pulling first; will overwrite');
+                await gistData.sync();
+                if (!simpleDeepCompare(lastGistData, gistData.data))
+                    await pushGist(octokit, filename, gistId, {
+                        description: overwriteDescription &&
+                            (!gist || gist.description !== overwriteDescription)
+                            ? overwriteDescription
+                            : undefined,
+                        contents: JSON.stringify(schema.encode(gistData.data), undefined, '  '),
+                    });
+            };
+            gistData.isLinked = true;
+        }
+    };
+    return gistData;
+};

package/dist/utils/index.js

@@ -1,8 +1,3 @@
-import * as tmp from 'tmp-promise';
-import chalk from 'chalk';
-import * as z from 'zod';
-import { confirm } from '@inquirer/prompts';
-import { editInteractively } from 'edit-like-git';
 export class AbortError extends Error {
     constructor(message) {
         super(message);
@@ -16,68 +11,11 @@ export function reorder(array, newIndecies) {
         array[idx] = originalArray[originalIdx];
     });
 }
-export const haveUserUpdateData = async (schema, data, options, checks) => {
-    const file = options?.file?.type && options.file.type === 'abs'
-        ? { path: options.file.path }
-        : await tmp.file({
-            prefix: options?.file?.type === 'tmp' ? options.file.prefix : undefined,
-            postfix: '.json',
-        });
-    let contents = JSON.stringify(schema instanceof z.ZodObject && options?.jsonSchemaUrl
-        ? { $schema: options?.jsonSchemaUrl, ...data }
-        : data, undefined, '  ');
-    let updatedResult = undefined;
-    while (true) {
-        const controller = new AbortController();
-        const signal = controller.signal;
-        const editorPromise = editInteractively(file.path, contents, options?.editor, options?.tooltips);
-        await new Promise((resolve) => setTimeout(resolve, 1000));
-        const abortPromise = confirm({ message: 'Type `y` to abort...' }, { signal })
-            .finally(() => {
-            process.stdout.moveCursor(0, -1);
-            process.stdout.clearLine(1);
-        })
-            .then(async (shouldAbort) => {
-            if (shouldAbort) {
-                if (file.cleanup)
-                    await file.cleanup();
-                throw new AbortError('User aborted action');
-            }
-        });
-        contents = await Promise.race([editorPromise, abortPromise]);
-        controller.abort();
-        if (typeof contents !== 'string')
-            return undefined;
-        if (checks?.preparse) {
-            const preparseError = checks?.preparse(contents);
-            if (preparseError === 'pass') {
-                updatedResult = undefined;
-                break;
-            }
-            else if (typeof preparseError === 'object') {
-                console.log(chalk.red(`${options?.errorHead}:`), preparseError.errMessage);
-                continue;
-            }
-        }
-        updatedResult = schema.safeParse(JSON.parse(contents));
-        if (updatedResult.success) {
-            if (checks?.postparse) {
-                const postparseError = checks?.postparse(updatedResult.data);
-                if (typeof postparseError === 'object') {
-                    console.log(chalk.red(`${options?.errorHead}:`), postparseError.errMessage);
-                    continue;
-                }
-            }
-            break;
-        }
-        console.log(chalk.red(`${options?.errorHead}:`), `JSON invalid: ${updatedResult.error.message}`);
+export const clearNLines = (n) => {
+    for (let i = 0; i < n; i++) {
+        process.stdout.moveCursor(0, -1);
+        process.stdout.clearLine(1);
     }
-    if (file.cleanup)
-        await file.cleanup();
-    return (updatedResult &&
-        (updatedResult.success
-            ? updatedResult.data
-            : (() => {
-                throw new Error(`${options?.errorHead}: JSON invalid: ${updatedResult.error.message}`);
-            })()));
+    process.stdout.cursorTo(0);
 };
+export const simpleDeepCompare = (a, b, replacer) => JSON.stringify(a, replacer) === JSON.stringify(b, replacer);

package/dist/utils/jsonData.js

@@ -1,17 +1,14 @@
 import fs from 'fs/promises';
-import * as z from 'zod';
-export const makeJsonData = async (jsonPath, schema) => {
+export const makeJsonData = async (jsonPath, schema, overrideJsonSchemaUrl, ...[toInput]) => {
     const json = JSON.parse(await fs.readFile(jsonPath, 'utf8').catch((error) => {
         throw new Error(`Couldn't open '${jsonPath}': ${error}`);
     }));
-    const schemaUrl = json['$schema'];
-    const parsed = schema.safeParse(json);
-    if (!parsed.success)
-        throw new Error(`JSON at '${jsonPath}' does not match schema: ${z.treeifyError(parsed.error)}`);
+    const schemaUrl = overrideJsonSchemaUrl ?? json['$schema'];
+    const data = schema.parse(json);
     const jsonData = {
-        data: parsed.data,
-        async sync() {
-            const encoded = schema.encode(jsonData.data);
+        data,
+        sync() {
+            const encoded = toInput ? toInput(jsonData.data) : jsonData.data;
             return fs.writeFile(jsonPath, JSON.stringify(typeof schemaUrl === 'string'
                 ? {
                     $schema: schemaUrl,

package/dist/utils/promptUser.js

@@ -0,0 +1,215 @@
+import * as z from 'zod';
+import * as tmp from 'tmp-promise';
+import chalk from 'chalk';
+import { confirm, select } from '@inquirer/prompts';
+import { editInteractively } from 'edit-like-git';
+import fs from 'fs/promises';
+import { AbortError, clearNLines } from './index.js';
+import { makeJsonData } from './jsonData.js';
+import { existsSync } from 'fs';
+import path from 'path';
+import { diffLines } from 'diff';
+export const haveUserUpdateContents = async (contents, options, check) => {
+    const file = options?.file?.type && options.file.type === 'abs'
+        ? { path: options.file.path }
+        : await tmp.file({
+            prefix: options?.file?.type === 'tmp' ? options.file.prefix : undefined,
+            postfix: '.json',
+        });
+    const originalContents = await fs.readFile(file.path, { encoding: 'utf8' });
+    while (true) {
+        const controller = new AbortController();
+        const signal = controller.signal;
+        const editorPromise = editInteractively(file.path, contents, options?.editor, options?.tooltips);
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        const abortPromise = confirm({ message: 'Type `y` to abort...' }, { signal })
+            .finally(() => clearNLines(1))
+            .then(async (shouldAbort) => {
+            if (shouldAbort) {
+                if (file.cleanup)
+                    await file.cleanup();
+                else
+                    await fs.writeFile(file.path, originalContents, {
+                        encoding: 'utf8',
+                    });
+                throw new AbortError('User aborted action');
+            }
+            return undefined;
+        });
+        contents = await Promise.race([editorPromise, abortPromise]);
+        controller.abort();
+        if (typeof contents !== 'string')
+            return undefined;
+        if (check) {
+            const error = check(contents);
+            if (error === 'pass') {
+                break;
+            }
+            else if (typeof error === 'object') {
+                console.log(chalk.red(`${options?.errorHead}:`), error.errMessage);
+                continue;
+            }
+        }
+    }
+    if (file.cleanup)
+        await file.cleanup();
+    return contents;
+};
+export const haveUserUpdateData = async (schema, data, options, checks) => {
+    const contents = JSON.stringify(schema instanceof z.ZodObject && options?.jsonSchemaUrl
+        ? { $schema: options?.jsonSchemaUrl, ...data }
+        : data, undefined, '  ');
+    let updatedData = undefined;
+    await haveUserUpdateContents(contents, options, (contents) => {
+        if (checks?.preparse) {
+            const preparseError = checks.preparse(contents);
+            if (preparseError !== 'continue') {
+                updatedData = undefined;
+                return preparseError;
+            }
+        }
+        try {
+            updatedData = schema.parse(JSON.parse(contents));
+            if (checks?.postparse) {
+                const postparseError = checks.postparse(updatedData);
+                if (typeof postparseError === 'object')
+                    return postparseError;
+            }
+            return 'pass';
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                return { errMessage: `Recieved invalid JSON: ${error.message}` };
+            else if (error instanceof z.ZodError)
+                return {
+                    errMessage: `JSON does not match schema:\n${z.prettifyError(error)}`,
+                };
+            else
+                throw error;
+        }
+    });
+    return updatedData;
+};
+export async function getDataTargetNicely(schema, target, recreateData, autoCreateFiles = false, ...conversionArg) {
+    let jsonData = undefined;
+    let hadToCreate = false;
+    try {
+        if (!existsSync(target.expectedPath))
+            throw new AbortError(`File '${target.expectedPath}' for ${target.name} does not exist`);
+        jsonData = await makeJsonData(target.expectedPath, schema, target.jsonSchemaUrl, ...conversionArg);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            console.log(chalk.red('[e]'), `Invalid JSON at '${target.expectedPath}'`);
+        }
+        else if (error instanceof z.ZodError) {
+            console.log(chalk.red('[e]'), `JSON at '${target.expectedPath}' does not match schema:\n${z.prettifyError(error)}`);
+        }
+        else if (error instanceof AbortError) {
+            console.log(chalk.red('[e]'), error.message);
+        }
+        else
+            throw error;
+        const shouldRegenerate = autoCreateFiles ||
+            (await confirm({
+                message: `Want to regenerate ${target.name}?`,
+            }).finally(() => clearNLines(1)));
+        if (shouldRegenerate) {
+            clearNLines(1);
+            console.log(chalk.blue('[i]'), `Creating ${target.name} at '${target.expectedPath}'...`);
+            hadToCreate = true;
+            const { encoded, newJsonPath, newJsonSchemaUrl } = await recreateData();
+            if (newJsonPath)
+                target.expectedPath = newJsonPath;
+            if (newJsonSchemaUrl)
+                target.jsonSchemaUrl = newJsonSchemaUrl;
+            const dir = path.dirname(target.expectedPath);
+            if (!existsSync(dir))
+                await fs.mkdir(dir, { recursive: true });
+            await fs.writeFile(target.expectedPath, JSON.stringify(typeof encoded === 'object' && target.jsonSchemaUrl
+                ? { $schema: target.jsonSchemaUrl, ...encoded }
+                : encoded, undefined, '  '));
+            jsonData = await makeJsonData(newJsonPath ?? target.expectedPath, schema, target.jsonSchemaUrl, ...conversionArg);
+        }
+        else
+            throw error;
+    }
+    if (!jsonData)
+        throw new Error(`Could not get data target ${target.name}`);
+    return { data: jsonData, hadToCreate };
+}
+export const inquirerConfirm = (message) => confirm({ message }).finally(() => clearNLines(1));
+const formatGitChange = (ours, theirs, removeExtraLine = false) => `<<<<<<< ours
+${ours}${removeExtraLine ? '' : '\n'}=======
+${theirs}${removeExtraLine ? '' : '\n'}>>>>>>> theirs
+`;
+export const resolveConflictLikeGit = async (schema, ours, theirs, editor) => {
+    const objStrings = [ours, theirs].map((o) => JSON.stringify(o, undefined, '  '));
+    const diff = diffLines(...objStrings);
+    let changeGroup = null;
+    const diffLikeGit = diff.reduce((diffString, change, idx) => {
+        if (!change.added && !change.removed) {
+            if (changeGroup) {
+                diffString += formatGitChange(...changeGroup, true);
+                changeGroup = null;
+            }
+            diffString += change.value;
+        }
+        else {
+            if (!changeGroup)
+                changeGroup = ['', ''];
+            changeGroup[change.added ? 1 : 0] += change.value;
+        }
+        if (changeGroup && idx === diff.length - 1)
+            diffString += formatGitChange(...changeGroup, true);
+        return diffString;
+    }, '');
+    let resolved = undefined;
+    await haveUserUpdateContents(diffLikeGit, {
+        editor,
+        errorHead: 'Resolve conflict failed',
+        file: { type: 'tmp', prefix: 'gist-confict' },
+        tooltips: ['Resolve the conflict.'],
+    }, (contents) => {
+        try {
+            resolved = schema.parse(JSON.parse(contents));
+            return 'pass';
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                return { errMessage: `Recieved invalid JSON: ${error.message}` };
+            else if (error instanceof z.ZodError)
+                return {
+                    errMessage: `JSON does not match schema:\n${z.prettifyError(error)}`,
+                };
+            else
+                throw error;
+        }
+    });
+    return resolved;
+};
+export const makeGistConflictHandler = (schema, editor) => async (ours, theirs) => {
+    console.log(chalk.yellow('[w]'), `Pulled gist is different than local JSON`);
+    const oursOrTheirs = await select({
+        message: 'Want to use ours or theirs?',
+        choices: [
+            { value: 'ours', description: '(local JSON)' },
+            { value: 'theirs', description: '(the gist)' },
+            { value: 'resolve', description: 'resolve manually' },
+        ],
+    });
+    return oursOrTheirs === 'theirs'
+        ? theirs
+        : oursOrTheirs === 'ours'
+            ? ours
+            : await resolveConflictLikeGit(schema, ours, theirs, editor);
+};
+export const handleInvalidGist = async (_, error) => {
+    let filename;
+    console.log(chalk.red('[e]'), `Pulled gist for '${filename}' is invalid: doesn't match schema:\n${error instanceof z.ZodError ? z.prettifyError(error) : error.message}"`);
+    const shouldContinue = await confirm({
+        message: 'Ignore gist contents and continue?',
+    });
+    if (!shouldContinue)
+        throw new Error(`Invalid gist for '${filename}' and user aborted`);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uss-stargazer/job-queue",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "A CLI app to keep track of jobs/tasks built around a couple of JSON files.",
   "author": "uss-stargazer",
   "license": "Apache-2.0",
@@ -23,15 +23,18 @@
     "build:release": "npm run clean && tsc -p tsconfig.release.json",
     "lint": "eslint .",
     "prettier": "prettier \"{src,__{tests}__}/**/*.{ts,mts}\" --config .prettierrc --write",
-    "prettier:check": "prettier \"{src,__{tests}__}/**/*.{ts,mts}\" --config .prettierrc --check"
+    "prettier:check": "prettier \"{src,__{tests}__}/**/*.{ts,mts}\" --config .prettierrc --check",
+    "test": "cross-env NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.2.0",
     "@inquirer/search": "^4.1.0",
+    "@octokit/rest": "^22.0.1",
     "ansi-escapes": "^7.2.0",
     "chalk": "^5.6.2",
     "clear": "^0.1.0",
     "commander": "^14.0.2",
+    "diff": "^8.0.3",
     "edit-like-git": "^1.0.2",
     "env-paths": "^4.0.0",
     "figlet": "^1.9.4",
@@ -42,14 +45,19 @@
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/eslint__js": "^8.42.3",
+    "@types/jest": "^30.0.0",
     "@types/node": "^25.0.6",
     "@typescript-eslint/parser": "^8.52.0",
+    "cross-env": "^10.1.0",
+    "dotenv": "^17.2.3",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.0.0",
+    "jest": "^30.2.0",
     "prettier": "^3.7.4",
     "rimraf": "^6.1.2",
     "ts-api-utils": "^2.4.0",
+    "ts-jest": "^29.4.6",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.52.0"
   }