Proposal for a tiddlywiki.info "run" configuration

[pmario]

TLDR;

The default workflow to start a TW server should be:

cd /path/to/TW5
tiddlywiki * --run
tiddlywiki <listed subdirectory with editions> --run

or if tiddlywiki is installed globally and the "editions" environment variables are set

tiddlywiki * --run
tiddlywiki <listed edition> --run

@Jermolene and others -- what do you think?

It may be possible to have 2 new commands. --find and --run

---

At the moment we can do the following:

tiddlywiki ./edtitions/pluginlibrary --build test-server

Which will use the pluguinlibrary "test-server" build configuration. But the "build" command can do much more than just build. It can "run" every command TiddlyWiki CLI knows.

As we can see below:

• First it modifies the "output" directory
• Then it runs a "--build library" command
• Then it starts the server with --listen port=8888

{
...
	"build": {
		"test-server": [
			"--output", "./editions/pluginlibrary/files/local/library/tmp",
			"--build", "library",
			"--listen", "port=8888"
		],
		"library": [
			"--makelibrary","$:/UpgradeLibrary",
			"--savelibrarytiddlers","$:/UpgradeLibrary","[prefix[$:/]] -[[$:/plugins/tiddlywiki/upgrade]] -[[$:/plugins/tiddlywiki/translators]] -[[$:/plugins/tiddlywiki/pluginlibrary]] -[[$:/plugins/tiddlywiki/jasmine]]","recipes/library/tiddlers/","$:/UpgradeLibrary/List",
			"--savetiddler","$:/UpgradeLibrary/List","recipes/library/tiddlers.json",
			"--rendertiddler","$:/plugins/tiddlywiki/pluginlibrary/library.template.html","index.html","text/plain"]
	}
}

---

The proposal is: Let us create a run command that can do what build can do. But it should be similar to --editions command if the full info is missing. Eg:

tiddlywiki tw --run should

• If the current directory is named "tw" search for tiddlywiki.info
• If the current directory starts with "tw" search for a tiddlywiki.info file
• Search all subdirectories that start with: "tw" for a tiddlywiki.info file
• read the info and looks for a run configuration
• If there is no run config ignore it
• If run config is found an the directory name is exactly "tw" use the default configuration and run it
• If there is no dir with the exact name "tw" go to the last step
• If run is found it should show the following info, similar to the --editions command

On my computer there are 7 edition directories TW will find

    tw.org: Content for https://tiddlywiki.org
    tw5.com: Documentation from https://tiddlywiki.com
    tw5.com-docs: Documentation from tw5.com edition
    tw5.com-server: Server configuration of the tw5.com edition
    tw5tank: Demo of Tank integration
    tw5tiddlyweb: Base edition for TiddlySpace integration
    twitter-archivist: Twitter Archivist Edition

But only tw5.com has a "run" configuration yet. So it will show:

1: tw5.com --run default
2: tw5.com --run lazy

So we can start it with tiddlywiki tw5.com --run default or tiddlywiki tw5.com --run

which in the end will run

tiddlywiki +plugins/tiddlywiki/filesystem +plugins/tiddlywiki/tiddlyweb ./editions/tw5.com --listen

Run Configuration in tw5.com

	"run": {
		"default": ["+plugins/tiddlywiki/filesystem", "+plugins/tiddlywiki/tiddlyweb", "./editions/tw5.com", " --listen"],
		"lazy": [
			"+plugins/tiddlywiki/filesystem", "+plugins/tiddlywiki/tiddlyweb", "./editions/tw5.com",
			"--listen","root-tiddler=$:/core/save/lazy-all"
		]

The good thing now is that the new run command does not depend on the TW directory structure anymore, since tw5.com and tw5.com-server can have different run configurations.
Editions are only shown, if they do have a run-configuration.

The new structure should be compatible with npm run eg:

NPM should be able to deal with npm run edition tw5.com --run lazy where we only need ''one'' "editions" script. So 1 edition script can handle all tw configurations.

This will keep package.json as simple as it can be. -- It should make tiddlywiki tw5.com --run even shorter. So we would not really need any NPM scripts anymore.

TLDR;

The default workflow to start a TW server should be:

cd /path/to/TW5
ls editions
tiddlywiki <listed subdirectory> --run

[Jermolene]

Hi @pmario there are quite a few ideas here, and I'm not sure I'm tracking them all:

• Using a wildcard "*" in the TW command line in place of the wiki folder path. What does that mean?
• Superseding the --build command with a new --run command. Why is the syntax --run="default"? There's no core command that uses that syntax. I would have expected --run default or --run command=default
• New rules for finding the tiddlywiki.info file relative to a specified directory. Some of the rules seem very arcane and arbitrary. What is the goal with these rules? I don't like the complexity; people need to be able to run these algorithms in their heads, and this one is very complex
• Specifying wiki folders with a prefix seems very brittle and error prone. If it is just intended to make it easier to type the folder name, why not just use terminal auto complete?

I am not sure that we want to encourage users to run the built-in editions directly. Users who have installed TW globally with npm will find that any changes they make to those wiki's are hidden away within npms global cache. I do see that there are use cases for running editions directly as wikis, but I think those are quite advanced use cases. For most users, the purpose of editions is to enable the --create command to create a new wiki from a template.

[pmario]

• Using a wildcard "*" in the TW command line in place of the wiki folder path. What does that mean?

At the moment the tiddlywiki command line parser expected "something" as the first parameter. IMO that's hard-coded. So imo we need to keep that signature for compatibility reasons.

It's like ls * ... So tiddlywiki * --run should list every edition, where the tiddlywiki.info file has a run configuration.

---

Superseding the --build command with a new --run command. Why is the syntax --run="default"? ...

I thought it is needed for compatibility reasons with npm run. But further testing shows that npm run server -- tw5.com --run default should be fine. So no different syntax is needed. (I'll change that in the OP)

---

New rules for finding the tiddlywiki.info file relative to a specified directory. Some of the rules seem very arcane and arbitrary. What is the goal with these rules? I don't like the complexity; people need to be able to run these algorithms in their heads, and this one is very complex

Those rules are not new. tiddlywiki --editions does the same thing.

• It starts at the current directory and searches every subdirecotry for a tiddlywiki.info file and lists it as an edtion
• Then it has a look at all paths and subdirectories listed in the TIDDLYWIKI_EDITION_PATH environment variable

The difference for tiddlywiki tw --run will be, that if tw is not a directory, it will fallback to "list all directories that start with: tw" and have a tiddlywiki.info run configuration.

---

Specifying wiki folders with a prefix seems very brittle and error prone. If it is just intended to make it easier to type the folder name, why not just use terminal auto complete?

The prefix is only active if it is used as a fallback to list all editions which start with the prefix. On my system tiddlyiwiki --editions returns a list with 134 elements. That's completely unusable without a proper filter.

On linux I would do tiddlywiki --editions | grep -i tw -- On windows I need a google search to find the equivalent powershell command. Which btw is tiddlywiki --editions | findstr tw (I'm pretty sure, that I will have forgotten that one, when I need it the next time)

But I doubt that our users will know what to search for.

Terminal auto complete only works with directories, that are physical subdirectories. It will not list editions which are connected with environment variables. We would need extra shell autocomplete software, that would be able to do that. But we do have to support several OSes :(

---

I am not sure that we want to encourage users to run the built-in editions directly. Users who have installed TW globally with npm will find that any changes they make to those wiki's are hidden away within npms global cache. I do see that there are use cases for running editions directly as wikis, but I think those are quite advanced use cases. For most users, the purpose of editions is to enable the --create command to create a new wiki from a template.

That's an argument. I did not think about that one. I did think about developers, that work in a git-branch developing TW.

That's what the extra commands in package.json would have been for. -- I'll need to think about that one.

[pmario]

I did adjust the OP so the parameters do not introduce a new syntax anymore.

[Jermolene]

At the moment the tiddlywiki command line parser expected "something" as the first parameter. IMO that's hard-coded. So imo we need to keep that signature for compatibility reasons.

The parser allows the wiki folder to be omitted by making the first token be a command prefixed with --

It's like ls * ... So tiddlywiki * --run should list every edition, where the tiddlywiki.info file has a run configuration.

I find it confusing that --run lists things rather than running things.

The difference for tiddlywiki tw --run will be, that if tw is not a directory, it will fallback to "list all directories that start with: tw" and have a tiddlywiki.info run configuration.

Thanks for elaborating the motivation. It is a difficult balance. I do wonder how many users treat editions in the same way.

Perhaps the best user experience would be if we implemented custom terminal completion hooks. Do they work on Windows?

That's an argument. I did not think about that one. I did think about developers, that work in a git-branch developing TW.

That's what the extra commands in package.json would have been for. -- I'll need to think about that one.

It still may be valid to ship with better developer scripts; we just need to make sure they are marked clearly as such.